service-remapping

APM サービスの再マッピング

作業を開始する前に： 予定しているルールを提示する前に、影響範囲のプレビュー（古いサービス名を参照しているモニター／ダッシュボード）を提示してください。推論されたエンティティの再マッピングでは、アウトバウンドスパンに peer.service が設定されていることも確認してください。## Context to resolve before acting の変数は、プレビューを妨げることなく、プレビューと並行して収集できます。

---

サービスの再マッピングの仕組み — ドメイン知識

ルールを作成する前に、これを読んでください。適切なフィルターを構築し、エッジケースを見つけるための考え方を説明します。

再マッピングの動作： ルールは取り込み時にテレメトリーを捕捉し、インデックス作成前にサービス名を書き換えます。ルールは、「このフィルターに一致するエンティティのサービス名を、この新しい値に置き換える」と指定します。

2 種類のエンティティ — 適切なものを選択してください：

エンティティタイプ	rule_type 整数値	対象
SERVICE	0	インストルメンテーションされたサービス — トレーサーによって明示的な service タグが設定されたスパンを持ちます
INFERRED_ENTITY	1	アウトバウンド呼び出しから自動検出されます — peer.service に基づいて名前が付けられます。アウトバウンドスパンに peer.service が設定されている必要があります（以下の前提条件を参照）。

推論されたエンティティの再マッピングの前提条件 — peer.service が設定されている必要があります：

推論されたエンティティの再マッピングは、トレーサーがアウトバウンドスパンに 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 がないスパンが表示され、サービス再マッピングルールは一致しません。

ルールを作成する前に peer.service が設定されていることを確認するには：

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

結果が 0 件の場合、トレーサーは peer.service を設定していません。先に進む前に、サービスの環境に DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true を追加して再デプロイするよう、ユーザーに依頼してください。

フィルター構文 — 標準的な Datadog イベント文法のクエリ文字列です：

目的	フィルター
サービス名の完全一致	service:payments
特定の接頭辞を持つすべてのサービス	service:deploy-test*
特定の接尾辞を持つすべてのサービス	service:*.tropos
特定の文字列を含むすべてのサービス	service:*payments*
特定のドメイン配下にあるすべての推論されたサービス	peer.service:*.shopify.com
1 つの環境におけるサービスのみ	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}}）を使用してください

5 つの再マッピングパターン：

パターン	ユーザーの説明…	フィルターの例	新しい名前の例
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 のサービス名を変更する
• 推定された複数のサービス名を 1 つにまとめる（例：複数の api.shopify.com/* のバリエーション → shopify）
• サービス名に含まれる環境サフィックス、バージョンタグ、デプロイメタデータを削除する
• peer.service の名前を意味のある名前に正規化する
• 組織変更、製品のブランド変更、または移行後にサービス名を変更する
• 1 つのサービスを環境ごとのバリエーションに分割する（my-service + env:prod → my-service-prod）
• 既存のサービスリマッピングルールを一覧表示、確認、または削除する

次の場合は、このスキルを呼び出さないでください。

• ユーザーがアプリケーションコード内のサービス名変更を希望している場合 — これにはリマッピングルールではなく、トレーサー設定（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 で動作します。作成、更新、削除には、apm_service_renaming_write が pup の OAuth スコープに追加されるまで、API キー（DD_API_KEY、DD_APP_KEY、DD_SITE）が必要です。

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）はインテグレーションによって生成されるオーバーライドです。ユーザーが設定した service タグではなく、使用されているライブラリに基づいて、トレーサーがスパンに自動でタグ付けします。これらをサービスのリマッピングルールでリマッピングするのは適切ではありません。オーバーライドはインテグレーションによってスパンごとに挿入されるため、オーバーライド自体を削除しない限り、リマッピング後の名前が何度も再び現れます。

検出方法： サービス名がよく知られたインテグレーション名（単一の単語で表されるライブラリ名、<protocol>-<client>形式、<vendor>.<resource>形式など）に見える場合は、ユーザーに確認してください。

「名前 <SERVICE> はインテグレーションのオーバーライドのようです。これはユーザーが設定したサービス名ではなく、<LIBRARY>インテグレーションからのスパンにトレーサーが自動で設定する名前です。オーバーライドはすべてのスパンで再適用されるため、ここではサービスのリマッピングが反映され続けません。適切な対処方法はインテグレーションのオーバーライド削除です。これにより自動設定された名前が削除され、代わりに親サービスの名前が引き継がれます。現在、これは 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 が設定されていることを確認してください。前提条件については「Domain Knowledge」を参照してください。設定されていない場合は、ここで終了し、まず DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true を有効にするようユーザーに依頼してください。

1c. フィルター

リマッピングするサービスを対象とするイベント文法のクエリ文字列を1つ作成します。「Domain Knowledge」にあるフィルター構文とパターンの表を使用して、適切な形式を選んでください。**計画したルールのプレビュー（Step 3）には、フィルター式をそのまま記載してください。**これは、ルールが対象のエンティティに一致することをユーザーが確認するための主要な方法であり、フィルター式がなければルールを評価できません。

1d. 新しい名前（value）

「Domain Knowledge」にある新しい名前の構文と正規表現の表を使用して、適切な形式を選んでください。正規表現を使う場合は、そこに記載された制約を適用してください。

1e. ルール名

内容が分かりやすい名前を提案してください。例：

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

---

Step 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

ユーザーに報告します：

項目	伝える内容
テレメトリ量	ゼロ以外のスパンがあれば、フィルターが実際のデータに一致することを確認できます。ゼロの場合は、サービス名または環境が間違っている可能性があります。
モニター	古いサービス名を参照しているモニターは、マッピング変更後に気づかないまま動作しなくなります。一覧を示し、更新を提案します。
ダッシュボード	タイトルに古いサービス名が含まれるダッシュボードは、マッピング変更後に古い参照が残ります。一覧を示し、更新を提案します。
競合するルール	同じサービスを対象とする既存のルールが上書きされる可能性があります。競合を示し、ユーザーに確認します。

既知の制限 — Claude は以下を自動的に確認できません：

サービス名をマッピングし直すと、以下にも影響する可能性があります。Claude には現時点で確認用の pup コマンドがないため、ユーザーが確認する前に手動チェックリストとして提示してください：

「このルールを作成する前に、以下のいずれにも <ORIGINAL_SERVICE> が参照されていないことをご確認ください。マッピング変更後も自動更新されません：

• スパンからメトリクスへのルール（APM → Setup → Generate Metrics）
• トレースからメトリクスへのルール
• スパン保持フィルター（APM → Setup → Retention Filters）
• ログからメトリクスへのルール（Logs → Generate Metrics）
• サービス名を対象とするパイプライン、アラート、または SLO」

モニターが古いサービス名を参照している場合は、次のように尋ねます：

「<ORIGINAL_SERVICE> を参照しているモニターが <N> 件見つかりました。マッピング変更後、<TARGET_NAME> を使うよう更新する必要があります。今すぐ更新しますか？」

---

ステップ 3：ルールを確認する

作成予定のルールをユーザーに提示し、作成前に確認します。未解決のコンテキスト変数はすべて同じプロンプトにまとめてください — それより前のターンで別途尋ねないでください。往復は 1 回で済ませ、2 回にしないでください。

フィルターで環境がまだ絞り込まれていない場合は、環境を追加するかどうかを尋ねます。環境の絞り込みは、別個の API パラメーターではなく、フィルター式に AND env:<ENV> を追加して行います。

「フィルター <FILTER> を使って <ORIGINAL_SERVICE> を <TARGET_NAME> にマッピングするルール <RULE_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 の値を記録します。

ERROR: 400 Bad Request with "Filter expression has invalid syntax" — フィルタークエリの形式が正しくありません。glob 構文とブール演算子を確認してください。

ERROR: 400 Bad Request with "Template value in target name is invalid" — value の正規表現が無効です。キャプチャグループは最大 1 つであること、グループ内の量指定子は非貪欲にすること（(.+?) であり、(.+) ではないこと）を確認してください。

ERROR: 401 Unauthorized — 認証情報が無効か、期限切れです。DD_API_KEY と DD_APP_KEY を再確認してください。

ERROR: 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）

推論されたエンティティは独自のスパンを生成しないため、pup apm services list または pup traces search には表示されません。次の 2 つの手順で確認します：

ステップ 5a — ルールが正しく保存されていることを確認する：

Claude の実行

pup apm service-remapping get <RULE_ID>

フィルターと値が意図した内容と一致していることを確認します。

ステップ 5b — サービスマップでエンティティ名が変更されたことを確認する：

Datadog UI の APM Service Map を確認し、以前 <ORIGINAL_SERVICE> が表示されていた場所に <TARGET_NAME> が表示されているか、ユーザーに確認してもらいます。サービスマップは、推論されたエンティティ名を確認するための信頼できる表示です。

別の方法として、計装されたサービスのスパンに新しい peer.service の値が届いていることを確認します：

Claude の実行

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

peer.service:<TARGET_NAME> を含むスパンが表示された場合、ルールは有効です。

エラー：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 サービスマップに新しいエンティティ名が表示されたことをユーザーが確認している、またはスパンに peer.service:<TARGET_NAME> が表示されている
• 影響を受けるモニターを特定し、更新を提案している
• マッピングが意図どおりであることをユーザーが確認している

---

セキュリティ上の制約

• 生の API キーをファイルやチャットメッセージに書き込まないでください。必ず $DD_API_KEY と $DD_APP_KEY を使用してください。
• ユーザーの明示的な確認なしに、ルールを作成または削除しないでください。作成前にルール全体を提示してください。
• prod を環境として決めつけないでください。必ずユーザーに確認してください。
• ルールの名前とフィルターを先にユーザーに示さずに、DELETE を実行しないでください。