Service remapping rules

Overview

Update how your services appear across Datadog without changing tracer configuration or redeploying code. Service remapping rules allow you to rename, merge, or split services; or create new services based on infrastructure tags from the Datadog UI. You can also create remapping rules for other entity types, such as inferred services, datastores, and queues.

Prerequisites

You must have the apm_service_renaming_write permission to create remapping rules. See Permissions for details on Datadog role-based access control.

Tracer version requirements

You can create service remapping rules only for services instrumented with supported tracer versions. If a service is reporting from an older tracer version, upgrade the SDK before creating remapping rules for that service.

Note: This only applies to instrumented services. There is no tracer version requirement to remap inferred services, datastores, or queues.

Create a service remapping rule

Step 1: Select remapping action and entities to target

1. In Datadog, navigate to APM > Catalog > Manage > Service Remapping. Click Add Service Rule to remap instrumented services. To remap inferred services, datastores, or queues, select the Inferred Entity Rules tab and click Add Inferred Entity Rule.

   Alternatively, navigate to APM > Catalog and click on a service to open the service side panel. From there, click Service Page > Service Remapping.

2. Choose a remapping action to perform for your new remapping rule.

   • Select Remap services to split a single entity, rename an entity, merge multiple entities together, or rename several entities.
   • Select Correlate telemetry to identify a service based on an infrastructure tag.

3. Use the search bar to select the entities you want to remap.

   • You can select one or more entities, but all must be of the same type (service, inferred service, datastore, or queue). Select services based on their service or peer.service tag, not by their Display Name metadata.
   • As you select entities, a span query is built in the background. To edit the query, select Build Advanced Query.
   • If you’re correlating a service with infrastructure tags, you can only select one service. Choose infra tag(s) to correlate telemetry on. All telemetry with the same infra tag(s) as the service chosen will be remapped to a single unified service name.

Step 2: Specify new entity name

In the text box, enter a unique name for the selected entity (or entities). Alternatively, use tag values with the {{tagName}} syntax to remap based on an entity’s tags. As you type, a preview of the new service name(s) appears.

1. If tag values follow a pattern, apply a regular expression to extract only the portion you want in the name. Note: The preview is not an exhaustive list. If you are remapping a service based on a tag with several values, only the values with the most spans appear in the preview.

Step 3: Name your rule and review

1. Optionally, enter a descriptive name for the remapping rule so you can identify it later.
2. Review and save your remapping rule. After you save your rule, it may take about a minute for it to take effect.

Remapping rules behavior

Remapping rules work by overriding the service tag for remapping services, or the peer.service tag for remapping inferred services, datastores, and queues. Services are remapped at intake, and any preexisting configuration specifying a service name does not change when a remapping rule is created. Service remapping rules take precedence over all other service name configurations.

Remapping rules are applied across APM, Logs, Metrics, USM, DSM, DJM, DBM, Profiling, NPM, Live Processes, Live Containers, Kubernetes, and Events.

• Historical data: Changes made by remapping rules affect only telemetry ingested while a rule is active, and past data is not updated retroactively. Deleting or modifying a rule stops it from applying to new data, but does not revert names on previously ingested data.
• Rule order: Service remapping rules are applied in order. Rules at the top of the rule list are applied first. A service is remapped only by the first rule that captures it (multiple rules are not applied to the same service).
• Regular expressions: Regular expressions can be used to define new service names, but greedy quantifiers are not allowed inside the capture group.
• Logs service remapper: Service remapping rules occur before logs pipelines. If the logs service remapper and remapping rules are both applied to a service, the remapping rules take precedence.
• Dashboards and monitors: Existing queries that reference old service names are not automatically updated. Review and update these manually. Integration and custom overrides: If integration overrides or custom overrides fall within the scope of a remapping rule, they are also remapped. Remove integration overrides for the best APM experience.
• Service naming hierarchy: Service names are determined by the following hierarchy, from highest to lowest priority:
  1. Service remapping rules
  2. Service defined in code (tracer.Start(WithService(xx)))
  3. Service defined in the system property (-Ddd.service={})
  4. Service defined in the environment variable (DD_SERVICE)
  5. Service defined in the config file (application_monitoring.yaml)

Request a personalized demo