service-remapping

APM 服务重映射

操作前： 在展示计划规则之前，先显示影响预览（引用旧服务名称的监控器／仪表板）。对于推断实体重映射，还需确认出站 Span 上已设置 peer.service。可在生成该预览的同时收集 ## Context to resolve before acting 中需要解析的变量，无需因此阻塞操作。

---

服务重映射的工作原理 — 领域知识

在构建规则前请先阅读本节，了解如何构造正确的筛选条件并捕捉边缘情况。

重映射的作用： 规则会在摄取时拦截遥测数据，并在建立索引前重写服务名称。规则的含义是：“对于任何符合此筛选条件的实体，将其服务名称替换为这个新值。”

两种实体类型 — 选择正确的类型：

实体类型	rule_type 整数值	目标对象
SERVICE	0	已插桩的服务 — 具有由追踪器设置了显式 service 标签的 Span
INFERRED_ENTITY	1	根据出站调用自动检测 — 根据 peer.service 命名。要求出站 Span 上已设置 peer.service（见下文前提条件）。

推断实体重映射的前提条件 — 必须设置 peer.service：

只有在追踪器为出站 Span 设置了 peer.service 时，推断实体重映射才会生效。如果未设置，实体将以 peer.hostname 为键，重映射规则也不会生效。

若要启用此功能，请在已插桩的服务（而非下游依赖项）上设置以下环境变量：

DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true

这样会使 ddtrace 追踪器在出站 HTTP、gRPC 和数据库调用中，自动从 peer.hostname 传递 peer.service。未启用时，pup traces search 会显示包含 peer.hostname 但不含 peer.service 的 Span，因此没有服务重映射规则会匹配。

在构建规则前，请验证是否已设置 peer.service：

pup traces search --query "@peer.service:<ENTITY_NAME>" --from 15m --limit 5

如果结果为零，说明追踪器未设置 peer.service。请让用户在服务环境中添加 DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true，并在继续前重新部署。

筛选语法 — 标准 Datadog 事件语法查询字符串：

目标	筛选条件
精确匹配服务	service:payments
所有带指定前缀的服务	service:deploy-test*
所有带指定后缀的服务	service:*.tropos
所有包含指定字符串的服务	service:*payments*
某个域下的所有推断服务	peer.service:*.shopify.com
仅匹配某个环境中的服务	service:payments AND env:prod
多个可能的值	service:(payments OR billing)

仅支持以下操作： 上述形式 — 精确匹配、通配符、AND／OR — 是唯一接受的操作。更高级的查询语法（CIDR 范围、数值比较、模糊匹配等）不受支持，API 会以筛选语法错误拒绝此类查询。

新名称语法 — rewrite_tag_rules 中的 value 字段：

形式	示例	用途
静态字符串	my-service	所有匹配的实体都将获得完全相同的名称
标签插值	{{service}}	替换为标签的完整值
标签 + 正则捕获	{{service|^(.+?)\..*$}}	提取标签值的一部分（非贪婪捕获）

{{tag\|regex}} 的正则限制：

• 每个表达式最多 1 个捕获组
• 捕获组内不得使用贪婪量词 — 请使用非贪婪形式：(.+?) 而非 (.+)，(.*?) 而非 (.*)
• 不允许对捕获组本身使用量词（例如 (foo)+）
• 没有捕获组 → 将整个匹配结果用作替换值
• 捕获组覆盖整个匹配内容（例如 ^(.*)$）目前会被 UI 拒绝，且很快也会被 API 拒绝 — 如果需要完整标签值，请使用标签插值（{{service}}），而非正则表达式

五种重映射模式：

模式	用户的表述……	筛选条件示例	新名称示例
N:1 分组	“这 N 个服务其实是同一种东西”	peer.service:*.shopify.com	shopify
去除后缀/前缀	“名称末尾/开头有多余内容”	service:*.tropos	{{service|^(.+?)\..*$}}
1:1 重命名	“我们重命名了这个服务，Datadog 需要匹配新名称”	service:old-auth-service	auth-service
按环境拆分	“我想为每个环境分别创建服务，但它们的名称都一样”	service:my-service AND env:prod	my-service-prod
前缀规范化	“所有服务都应以环境或团队名称开头”	service:payments*	{{env}}-{{service}}

---

触发条件

当用户希望执行以下操作时，调用此技能：

• 在不重新插桩的情况下重命名 Datadog 中的服务
• 将多个推断出的服务名称合并为一个（例如，将许多 api.shopify.com/* 变体合并为 shopify）
• 去除嵌入服务名称中的环境后缀、版本标签或部署元数据
• 将 peer.service 名称规范化为有意义的名称
• 在组织变更、产品品牌重塑或迁移后重命名服务
• 将单个服务按环境拆分为多个变体（my-service + env:prod → my-service-prod）
• 列出、查看或删除现有的服务重映射规则

以下情况不要调用此技能：

• 用户想在应用程序代码中重命名服务——这需要更改 tracer 配置（DD_SERVICE），而不是添加重映射规则
• 用户想要关联基础设施标签中的遥测数据——这对应 UI 中的“关联遥测数据”操作类型，而不是重映射

---

前提条件

pup-cli：检查、安装和进行身份验证

Claude 运行

pup --version

如果未找到：

Claude 运行

brew tap datadog-labs/pack
brew install pup

检查身份验证状态：

pup auth status

如果尚未通过身份验证：

Claude 运行

pup auth login

此操作会打开一个浏览器标签页以进行 OAuth。请在那里完成登录——命令退出后，Claude 将继续执行。

写入操作所需的凭据

pup apm service-remapping list 和 get 可使用 OAuth。创建、更新和删除操作需要 API 密钥（DD_API_KEY、DD_APP_KEY、DD_SITE），直到将 apm_service_renaming_write 添加到 pup 的 OAuth 作用域中。

Claude 运行

echo "DD_API_KEY set: $([ -n "${DD_API_KEY:-}" ] && echo yes || echo no)"
echo "DD_APP_KEY set: $([ -n "${DD_APP_KEY:-}" ] && echo yes || echo no)"
echo "DD_SITE: ${DD_SITE:-not set (defaulting to datadoghq.com)}"

如果缺少任何凭据，且你需要创建/更新/删除规则：

你需要在终端中执行的操作

export DD_API_KEY=<your-api-key>
export DD_APP_KEY=<your-app-key>
export DD_SITE=datadoghq.com   # adjust for your site

常见站点：datadoghq.com（US1）、datadoghq.eu（EU1）、us3.datadoghq.com、us5.datadoghq.com、ap1.datadoghq.com

等待用户设置凭据，然后重新运行上述检查，再继续操作。

---

操作前需要确定的上下文

变量	确定方式
ENV	创建规则前（第 4 步）必须确定。询问用户——不要假设为 prod。只读验证和影响预览不需要 ENV，应先执行。
ORIGINAL_SERVICE	要重映射的当前服务名称——使用 pup apm services list 查找，或询问用户
ENTITY_TYPE	已插桩的服务（rule_type: 0）还是推断出的实体（rule_type: 1）？如果不明确，请询问——参见“领域知识”
TARGET_NAME	所需的新服务名称——询问用户
PATTERN	适用的模式——根据用户的描述确定（参见上文“领域知识”）

---

步骤 0：发现当前服务名称

如果用户没有指定要重映射的确切名称，先查找现有服务：

Claude 运行

pup apm services list --from 1h          # use --env <ENV> to target a single environment
pup traces search --query "service:<PARTIAL_NAME>" --from 1h --limit 20

利用输出帮助用户确认确切的服务名称。继续操作前，询问用户确认要重映射哪些名称。

---

步骤 1：构建规则

写入任何 JSON 之前，先逐项处理各个组成部分。

1a. 检查集成覆盖名称

某些服务名称（例如 grpc-client、net/http、aws.s3、redis）是由集成生成的覆盖名称——追踪器会根据所用的库自动为 Span 添加这些名称，而不是由用户设置 service 标签。使用服务重映射规则来重映射这些名称并不合适：集成会逐个 Span 注入覆盖名称，因此除非移除覆盖名称本身，否则重映射后的名称会不断重新出现。

**检测方法：**如果服务名称看起来像常见的集成名称（单词形式的库名称、<protocol>-<client> 模式、<vendor>.<resource> 模式），请询问用户：

“名称 <SERVICE> 看起来像是集成覆盖名称——追踪器会自动将其设置为来自 <LIBRARY> 集成的 Span 名称，而不是用户配置的服务名称。服务重映射在这里不会生效，因为每个 Span 上都会重新应用该覆盖名称。正确的修复方法是移除集成覆盖名称，这样这些自动名称就会被清除，父服务的名称会随之传播。目前只能在 Datadog UI 的 APM → Setup → Service Remapping → Integration Override Removal 中进行配置。你想在那里处理，还是仍要继续创建重映射规则？”

如果用户确认这是集成覆盖名称，请到此为止，并引导用户前往 UI。不要创建重映射规则。

1b. 实体类型

[DECISION: entity type — ask the user if unclear]

• 服务是否因追踪器显式设置了它的 service 标签而出现？→ rule_type: 0（SERVICE）
• 服务是否通过出站调用（例如数据库、队列或外部 API）出现在服务映射中？→ rule_type: 1（INFERRED_ENTITY）

如果用户想要重映射推断实体，请在继续之前确认已设置 peer.service——请参阅领域知识中的前置条件。如果尚未设置，请停止并询问用户是否先启用 DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true。

1c. 筛选器

编写单个事件语法查询字符串，以定位要重映射的服务。使用领域知识中的筛选器语法和模式表，选择合适的形式。在计划规则预览（第 3 步）中逐字显示筛选表达式——这是用户验证规则是否会匹配目标实体的主要方式，没有它，用户就无法评估规则。

1d. 新名称（value）

使用领域知识中的新名称语法和正则表达式表，选择合适的形式。对于正则表达式值，请遵循其中列出的限制。

1e. 规则名称

建议使用描述性名称。示例：

• collapse-shopify-inferred-services
• strip-tropos-suffix
• rename-old-auth-to-auth-service
• env-split-my-service-prod

---

步骤 2：预览影响

构造 JSON 前，检查将受到哪些影响：

Claude 执行

# Confirm telemetry exists for the targeted service (zero spans = wrong query or wrong env)
pup traces search --query "service:<ORIGINAL_SERVICE>" --from 15m --limit 5

# Check for monitors referencing the old service name
pup monitors list | grep -i "<ORIGINAL_SERVICE>"

# Check for dashboards referencing the old service name
pup dashboards list | grep -i "<ORIGINAL_SERVICE>"

# List existing service remapping rules that may conflict
pup apm service-remapping list

向用户报告：

项目	需要说明的内容
遥测数据量	非零的 span 表示筛选条件能匹配到真实数据。为零则可能是服务名称或环境不正确。
监控器	任何引用旧服务名称的监控器都会在重新映射后悄然失效。列出它们，并提出更新。
仪表板	标题中包含旧服务名称的任何仪表板，在重新映射后都会保留过时的引用。列出它们，并提出更新。
冲突规则	现有的、针对同一服务的规则可能会被覆盖。展示冲突并请用户确认。

已知局限 — Claude 无法自动验证以下内容：

重新映射服务名称也可能导致以下内容失效。Claude 目前没有可用于检查这些内容的 pup 命令，因此请在用户确认前将其作为手动检查清单展示：

"创建此规则前，请确认 <ORIGINAL_SERVICE> 未在以下任何位置被引用——重新映射后，这些引用不会自动更新：

• Spans-to-metrics 规则（APM → Setup → Generate Metrics）
• Trace-to-metrics 规则
• Span 保留筛选器（APM → Setup → Retention Filters）
• Logs-to-metrics 规则（Logs → Generate Metrics）
• 任何作用于服务名称的流水线、告警或 SLO"

如果监控器引用了旧服务名称，请询问：

"我发现有 <N> 个监控器引用了 <ORIGINAL_SERVICE>。重新映射后，需要将它们更新为使用 <TARGET_NAME>。要我现在更新吗？"

---

步骤 3：确认规则

向用户展示计划创建的规则，并在创建前确认。将任何尚未解决的上下文变量一并放入同一个提示中——不要在更早的对话轮次中单独询问。一次往返，而不是两次。

如果筛选条件尚未限定环境，请询问是否要添加环境范围——环境范围通过在筛选表达式后追加 AND env:<ENV> 来设置，而不是通过单独的 API 参数设置。

"我计划创建规则 <RULE_NAME>，筛选条件为 <FILTER>，将 <ORIGINAL_SERVICE> 映射到 <TARGET_NAME>（rule_type：<TYPE>）。是否应将此规则限定到特定环境？如果是，我会在筛选条件中添加 AND env:<ENV>。可以继续吗？"

继续前请等待确认。

---

步骤 4：创建规则

Claude 执行

pup apm service-remapping create \
  --name "<RULE_NAME>" \
  --filter "<FILTER>" \
  --rule-type <TYPE> \
  --value "<TARGET_NAME>"

如果响应包含 id 字段，则表示创建成功。记录响应中的 id 和 version 值。

错误：400 Bad Request，提示 "Filter expression has invalid syntax" —— 筛选查询格式错误。请检查 glob 语法和布尔运算符。

错误：400 Bad Request，提示 "Template value in target name is invalid" —— value 正则表达式无效。请检查：最多只能有 1 个捕获组；组内使用非贪婪量词（使用 (.+?)，而不是 (.+)）。

错误：401 Unauthorized —— 凭据无效或已过期。请重新检查 DD_API_KEY 和 DD_APP_KEY。

错误：403 Forbidden —— API 密钥缺少 apm_service_renaming_write 权限。

---

步骤 5：验证

等待 2–5 分钟，让规则完成传播，然后确认规则已激活。

对于 SERVICE 规则（rule_type 0）

Claude 执行

# Confirm new service name appears in APM
pup apm services list --env <ENV> --from 5m

# Confirm traces are arriving under the new name
pup traces search --query "service:<TARGET_NAME>" --from 5m --limit 5

如果 <TARGET_NAME> 出现在任一结果中，则表示规则已激活。

对于 INFERRED_ENTITY 规则（rule_type 1）

推断实体不会生成自己的 span，因此不会出现在 pup apm services list 或 pup traces search 中。请分两步验证：

步骤 5a — 确认规则已正确保存：

Claude 执行

pup apm service-remapping get <RULE_ID>

确认筛选条件和 value 符合预期。

步骤 5b — 确认服务映射中实体名称已更改：

请用户在 Datadog UI 中检查 APM Service Map，确认 <ORIGINAL_SERVICE> 原先所在的位置现在显示的是 <TARGET_NAME>。对于推断实体名称，服务映射是权威视图。

或者，确认来自已检测服务的 span 中正在收到新的 peer.service 值：

Claude 运行

pup traces search --query "service:<INSTRUMENTED_SERVICE> @peer.service:<TARGET_NAME>" --from 5m --limit 5

如果出现带有 peer.service:<TARGET_NAME> 的 span，则表示规则已生效。

错误：5 分钟后仍未显示新名称：

• 确认旧服务仍在发送带有原始 peer.service 的追踪数据：pup traces search --query "@peer.service:<ORIGINAL_SERVICE>" --from 5m
• 如果仍显示旧名称，可能仍在传播中——再等待 2 分钟后重试
• 如果两个名称都未显示，请确认已在经过检测的服务上设置 DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true——如果未设置，则永远不会设置 peer.service，规则也永远不会触发

---

管理现有规则

列出所有规则

Claude 运行

pup apm service-remapping list

获取单条规则

Claude 运行

pup apm service-remapping get <RULE_ID>

更新规则

更新需要使用 list/get 输出中的当前 version。先向用户展示拟议的更改并征得确认，然后再执行：

Claude 运行

pup apm service-remapping update <RULE_ID> \
  --name "<RULE_NAME>" \
  --filter "<FILTER>" \
  --rule-type <TYPE> \
  --value "<NEW_NAME>" \
  --version <VERSION>

错误：409 Conflict——自获取规则以来，该规则已被修改。请使用 get 重新获取当前版本并重试。

删除规则

先向用户展示规则名称和筛选条件，然后征求确认。删除需要使用 list/get 输出中的规则 id 和 version：

Claude 运行

pup apm service-remapping delete <RULE_ID> <RULE_VERSION>

错误：409 Conflict——自获取规则以来，该规则已被修改。请使用 get 重新获取当前版本并重试。

---

完成

仅当以下所有条件均满足时才退出：

• 创建前已向用户展示规则并获得确认
• 规则已创建，且响应中返回了 id
• 对于 SERVICE 规则：在 pup apm services list 或 pup traces search 中可见新服务名称
• 对于 INFERRED_ENTITY 规则：用户确认 APM Service Map 中出现了新实体名称，或 span 显示 peer.service:<TARGET_NAME>
• 已识别受影响的监控项，并提出更新建议
• 用户确认重新映射符合其意图

---

安全约束

• 切勿将原始 API 密钥写入任何文件或聊天消息——始终使用 $DD_API_KEY 和 $DD_APP_KEY
• 未经用户明确确认，切勿创建或删除规则——创建前先展示完整规则
• 切勿假定环境为 prod——务必向用户确认
• 执行 DELETE 前，务必先向用户展示规则名称和筛选条件