Service Remapping

APM Service Remapping

Before acting: Surface an impact preview (monitors/dashboards referencing the old service name) before presenting the planned rule. For inferred-entity remaps, also confirm peer.service is set on outbound spans. Variables from ## Context to resolve before acting can be gathered alongside that preview rather than blocking it.

How Service Remapping Works — Domain Knowledge

Read this before building any rule. It gives you the mental model to construct the right filter and catch edge cases.

What remapping does: A rule intercepts telemetry at ingestion time and rewrites the service name before indexing. A rule says: "for any entity matching this filter, replace its service name with this new value."

Two entity types — pick the right one:

Prerequisite for inferred entity remapping — `peer.service` must be set:

Inferred entity remapping only works when the tracer sets peer.service on outbound spans. Without it, entities are keyed by peer.hostname and remapping rules will not apply.

To enable this, set the following env var on the instrumented service (not the downstream dependency):

DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true

This makes the ddtrace tracer automatically propagate peer.service from peer.hostname on outbound HTTP, gRPC, and database calls. Without this, pup traces search will show spans with peer.hostname but no peer.service, and no service remapping rule will match.

To verify peer.service is being set before building a rule:

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

If zero results — the tracer is not setting peer.service. Ask the user to add DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true to their service's environment and redeploy before continuing.

Filter syntax — a standard Datadog event-grammar query string:

Supported operations only: The above forms — exact match, wildcards, AND/OR — are the only accepted operations. More advanced query syntax (CIDR ranges, numeric comparisons, fuzzy matching, etc.) is not supported and will be rejected by the API with a filter syntax error.

New name syntax — the value field in rewrite_tag_rules:

Regex constraints for `{{tag\|regex}}`:

• Maximum 1 capture group per expression
• No greedy quantifiers inside capture groups — use non-greedy variants: (.+?) not (.+), (.*?) not (.*)
• Quantifiers on capture groups themselves (e.g. (foo)+) are not allowed
• No capture group → the entire match is used as the replacement value
• Capture group spanning the entire match (e.g. ^(.*)$) is currently rejected by the UI and will soon be rejected by the API — if you want the full tag value, use tag interpolation ({{service}}) instead of a regex

Five remapping patterns:

Triggers

Invoke this skill when the user wants to:

• Rename a service in Datadog without re-instrumenting
• Collapse multiple inferred service names into one (e.g. many api.shopify.com/* variants → shopify)
• Strip environment suffixes, version tags, or deployment metadata baked into service names
• Normalize peer.service names to something meaningful
• Rename a service after an org change, product rebrand, or migration
• Split a single service into per-env variants (my-service + env:prod → my-service-prod)
• List, review, or delete existing service remapping rules

Do NOT invoke this skill if:

• The user wants to rename the service in their application code — that requires a tracer config change (DD_SERVICE), not a remapping rule
• The user wants to correlate telemetry across infrastructure tags — that is the "Correlate telemetry" action type in the UI, not remapping

Prerequisites

pup-cli: check, install, and authenticate

Claude runs

pup --version

If not found:

Claude runs

brew tap datadog-labs/pack
brew install pup

Check auth:

pup auth status

If not authenticated:

Claude runs

pup auth login

This opens a browser tab for OAuth. Complete the login there — Claude will continue once the command exits.

Credentials for write operations

pup apm service-remapping list and get work with OAuth. Create, update, and delete require API keys (DD_API_KEY, DD_APP_KEY, DD_SITE) until apm_service_renaming_write is added to pup's OAuth scopes.

Claude runs

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)}"

If any are missing and you need to create/update/delete rules:

What you need to do in a terminal

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

Common sites: datadoghq.com (US1), datadoghq.eu (EU1), us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com

Wait for the user to set credentials, then re-run the check above before continuing.

Context to resolve before acting

Step 0: Discover Current Service Names

If the user hasn't specified exact names to remap, discover what exists first:

Claude runs

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