在 Datadog APM…

当需要在 Datadog 中重命名服务、合并碎片化的推断服务名、清理自动生成或带后缀的服务名、或按环境拆分服务时，用服务重映射规则在摄取时改写服务名，而无需重新插桩。

适用场景

解决思路

1. 行动前先给出影响预览（引用旧服务名的 monitors/dashboards），再展示计划规则；对推断实体重映射还要确认出站 span 上已设置 peer.service。
2. 理解重映射机制：规则在摄取时拦截遥测并在索引前改写服务名，即“对匹配此过滤器的实体，把服务名替换为新值”。
3. 选择正确的实体类型：SERVICE 用 rule_type 0（由 tracer 显式设置 service 标签的已插桩服务）；INFERRED_ENTITY 用 rule_type 1（从出站调用自动检测、由 peer.service 命名，且要求出站 span 上设置了 peer.service）。
4. 推断实体重映射的前置条件：在已插桩服务（不是下游依赖）上设置环境变量 DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true，使 ddtrace 在出站 HTTP、gRPC 和数据库调用上自动从 peer.hostname 传播 peer.service；否则实体以 peer.hostname 为键，规则不会匹配。
5. 构建规则前用 pup traces search --query "@peer.service:<ENTITY_NAME>" --from 15m --limit 5 验证 peer.service 是否已设置；若为零结果，请用户添加 DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true 并重新部署后再继续。
6. 使用标准 Datadog event-grammar 查询字符串作为过滤器：精确匹配 service:payments；前缀 service:deploy-test*；后缀 service:*.tropos；包含 service:*payments*；某域下所有推断服务 peer.service:*.shopify.com；仅某环境 service:payments AND env:prod；多值 service:(payments OR billing)。
7. 只使用受支持的操作（精确匹配、通配符、AND/OR）；更高级语法（CIDR、数值比较、模糊匹配等）不被支持，API 会以过滤器语法错误拒绝。
8. 新名称（rewrite_tag_rules 的 value 字段）可用：静态字符串（如 my-service）；标签插值（如 {{service}}）；标签加正则捕获（如 {{service|^(.+?)\..*$}}）提取标签值的一部分。
9. 正则约束：每个表达式最多 1 个捕获组；捕获组内不能用贪婪量词，用非贪婪变体 (.+?) 而非 (.+)、(.*?) 而非 (.*)；捕获组本身不能加量词（如 (foo)+）；无捕获组时整个匹配作为替换值；跨越整个匹配的捕获组（如 ^(.*)$）目前被 UI 拒绝且即将被 API 拒绝，若要完整标签值请用标签插值 {{service}}。
10. 识别五种重映射模式：N:1 分组（如 peer.service:*.shopify.com → shopify）；剥离后缀/前缀（如 service:*.tropos → {{service|^(.+?)\..*$}}）；1:1 重命名（如 service:old-auth-service → auth-service）；环境拆分（如 service:my-service AND env:prod → my-service-prod）；前缀规范化（如 service:payments* → {{env}}-{{service}}）。
11. 检查 pup-cli：运行 pup --version；若未安装，运行 brew tap datadog-labs/pack && brew install pup；用 pup auth status 检查认证，未认证则运行 pup auth login（会打开浏览器 OAuth）。
12. 写操作凭据：list 和 get 可用 OAuth；create、update、delete 需要 API keys（DD_API_KEY、DD_APP_KEY、DD_SITE），直到 apm_service_renaming_write 加入 pup 的 OAuth scopes。用 echo 检查这些变量是否已设置，缺失时请用户在终端 export DD_API_KEY=<your-api-key>、DD_APP_KEY=<your-app-key>、DD_SITE=datadoghq.com（按站点调整，如 datadoghq.eu、us3.datadoghq.com、us5.datadoghq.com、ap1.datadoghq.com），设置后重新检查再继续。
13. 行动前解析上下文变量：ENV（创建规则前必须向用户确认，不要假设 prod；只读验证和影响预览不需要 ENV，应先运行）；ORIGINAL_SERVICE（用 pup apm services list 发现或询问用户）；ENTITY_TYPE（已插桩服务 rule_type 0 还是推断实体 rule_type 1，不清楚就问）；TARGET_NAME（询问用户）；PATTERN（根据用户描述识别）。
14. Step 0 发现当前服务名：若用户未指定确切名称，运行 pup apm services list --from 1h（可用 --env <ENV> 限定单一环境）和 pup traces search --query "service:<PARTIAL_NAME>" --from 1h --limit 20，帮助用户识别确切服务名并确认要重映射的名称。
15. Step 1a 检查集成覆盖名：若服务名看起来像知名集成名（单词库名、<protocol>-<client> 模式、<vendor>.<resource> 模式，如 grpc-client、net/http、aws.s3、redis），说明这是 tracer 按库自动打的集成覆盖名，重映射不会生效，正确做法是集成覆盖移除（目前仅在 Datadog UI 的 APM → Setup → Service Remapping → Integration Override Removal 配置）；若用户确认是集成覆盖，停止并引导到 UI，不要创建重映射规则。
16. Step 1b 确定实体类型：服务因 tracer 显式设置 service 标签而出现 → rule_type 0；服务因出站调用（数据库、队列、外部 API）出现在服务图中 → rule_type 1；若要重映射推断实体，先验证 peer.service 已设置，未设置则停止并请用户先启用 DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true。
17. Step 1c 编写过滤器：用单一 event-grammar 查询字符串定位要重映射的服务，按过滤器语法和模式表选择形式，并在 Step 3 的计划规则预览中逐字给出过滤器表达式。
18. Step 1d 选择新名称（value）：按新名称语法和正则表选择形式，正则值应用上述约束。
19. Step 1e 建议描述性规则名，如 collapse-shopify-inferred-services、strip-tropos-suffix、rename-old-auth-to-auth-service、env-split-my-service-prod。
20. Step 2 预览影响：运行 pup traces search --query "service:<ORIGINAL_SERVICE>" --from 15m --limit 5 确认有遥测（零 span 说明查询或环境错误）；pup monitors list | grep -i "<ORIGINAL_SERVICE>" 检查 monitors；pup dashboards list | grep -i "<ORIGINAL_SERVICE>" 检查 dashboards；pup apm service-remapping list 检查冲突规则。向用户报告遥测量、monitors、dashboards、冲突规则。
21. 向用户给出无法自动验证的手动检查清单：重映射还可能破坏 spans-to-metrics 规则、trace-to-metrics 规则、span retention filters、logs-to-metrics 规则，以及任何按服务名动作的 pipeline、alert 或 SLO，这些不会自动更新。
22. 若 monitors 引用旧服务名，询问是否现在更新为 TARGET_NAME。
23. Step 3 确认规则：展示计划规则并在创建前确认，把未解析的上下文变量合并到同一提示中（一次往返，不要分两轮）；若过滤器未限定环境，询问是否追加 AND env:<ENV>（环境限定通过过滤器表达式实现，不是单独 API 参数）。
24. Step 4 创建规则：运行 pup apm service-remapping create --name "<RULE_NAME>" --filter "<FILTER>" --rule-type <TYPE> --value "<TARGET_NAME>"；响应含 id 即成功，记录 id 和 version。处理错误：400 过滤器语法无效；400 目标名模板值无效（检查最多 1 个捕获组、组内非贪婪量词）；401 凭据无效或过期；403 API key 缺少 apm_service_renaming_write 权限。
25. Step 5 验证：等待 2–5 分钟传播。SERVICE 规则（rule_type 0）运行 pup apm services list --env <ENV> --from 5m 和 pup traces search --query "service:<TARGET_NAME>" --from 5m --limit 5，出现 TARGET_NAME 即生效。
26. INFERRED_ENTITY 规则（rule_type 1）分两步验证：5a 运行 pup apm service-remapping get <RULE_ID> 确认过滤器与值正确；5b 请用户在 Datadog UI 的 APM Service Map 中查看 TARGET_NAME 是否出现在原 ORIGINAL_SERVICE 位置（服务图是推断实体名的权威视图），或运行 pup traces search --query "service:<INSTRUMENTED_SERVICE> @peer.service:<TARGET_NAME>" --from 5m --limit 5，出现 peer.service:<TARGET_NAME> 即生效。
27. 新名称 5 分钟后未出现时排查：运行 pup traces search --query "@peer.service:<ORIGINAL_SERVICE>" --from 5m 确认旧服务仍在发送原 peer.service；若旧名仍出现，传播可能仍在进行，再等 2 分钟重试；若两个名字都不出现，确认已插桩服务上设置了 DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true，否则 peer.service 永不设置、规则永不触发。
28. 管理现有规则：pup apm service-remapping list 列出全部；pup apm service-remapping get <RULE_ID> 获取单条；更新需从 list/get 输出取得当前 version，先向用户展示变更并确认，再运行 pup apm service-remapping update <RULE_ID> --name "<RULE_NAME>" --filter "<FILTER>" --rule-type <TYPE> --value "<NEW_NAME>" --version <VERSION>；409 Conflict 说明规则已被修改，用 get 重新获取当前 version 后重试。
29. 删除规则：先向用户展示规则名和过滤器并确认，删除需 id 和 version，运行 pup apm service-remapping delete <RULE_ID> <RULE_VERSION>；409 Conflict 时用 get 重新获取 version 后重试。
30. 完成条件：规则创建前已展示并确认；创建后响应返回 id；SERVICE 规则新名出现在 pup apm services list 或 pup traces search；INFERRED_ENTITY 规则用户确认新实体名出现在 APM Service Map 或 span 显示 peer.service:<TARGET_NAME>；已识别受影响 monitors 并提供更新；用户确认重映射符合意图。
31. 安全约束：绝不把原始 API key 写入任何文件或聊天消息，始终使用 $DD_API_KEY 和 $DD_APP_KEY；未经用户明确确认绝不创建或删除规则，创建前展示完整规则；绝不假设环境为 prod，始终与用户确认；未经展示规则名和过滤器绝不运行 DELETE。

适用边界 · 注意事项

• 用户想在应用代码中重命名服务——这需要 tracer 配置变更（DD_SERVICE），而不是重映射规则。
• 用户想跨基础设施标签关联遥测——那是 UI 中的 "Correlate telemetry" 动作类型，不是重映射。
• 服务名是集成生成的覆盖名（如 grpc-client、net/http、aws.s3、redis）——重映射不会生效，应使用集成覆盖移除（目前仅 UI 可配置）。