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

Use the output to help the user identify exact service names. Ask the user to confirm which names they want remapped before proceeding.

Step 1: Build the Rule

Work through each component before writing any JSON.

1a. Check for integration override names

Some service names (e.g. grpc-client, net/http, aws.s3, redis) are integration-generated overrides — the tracer auto-tags spans with them based on the library being used, not a user-set service tag. Remapping these with a service remapping rule is the wrong tool: the override is injected per-span by the integration, so the remapped name will keep re-appearing unless the override itself is removed.

How to detect: if the service name looks like a well-known integration name (single-word library names, <protocol>-<client> patterns, <vendor>.<resource> patterns), ask the user:

"The name <SERVICE> looks like an integration override — a name the tracer sets automatically on spans from the <LIBRARY> integration, not a user-configured service name. Service remapping won't stick here because the override is re-applied on every span. The right fix is integration override removal, which strips these auto-names so the parent service's name propagates instead. This is currently only configurable in the Datadog UI under APM → Setup → Service Remapping → Integration Override Removal. Do you want to handle it there, or proceed with a remapping rule anyway?"

If the user confirms it is an integration override, stop here and direct them to the UI. Do not create a remapping rule.

1b. Entity type

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

• Does the service appear because a tracer explicitly set its service tag? → rule_type: 0 (SERVICE)
• Does it appear in the service map from outbound calls (e.g. a database, queue, or external API)? → rule_type: 1 (INFERRED_ENTITY)

If the user wants to remap an inferred entity, verify peer.service is set before proceeding — see the prerequisite in Domain Knowledge. If it is not set, stop and ask the user to enable DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED=true first.

1c. Filter

Write a single event-grammar query string targeting the service(s) to remap. Use the filter syntax and pattern table in Domain Knowledge to pick the right form. State the filter expression verbatim in the planned-rule preview (Step 3) — it is the user's primary way to verify the rule will match the intended entities, and they cannot evaluate the rule without it.

1d. New name (value)

Use the new name syntax and regex table in Domain Knowledge to pick the right form. For regex values, apply the constraints listed there.