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 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 tracer before creating remapping rules for that service.

Create a service remapping rule

Step 1: Select remapping action and entities to target

1. In Datadog, navigate to APM > Software Catalog > Manage > Manage Renaming Rules and click + Add Rule.

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

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

   • You can select to split a single entity, rename an entity, merge multiple entities together, or rename several entities.
   • You can also choose to identify a service based on infrastructure tags.

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

   • You can select one or more entities, but all must be of the same type (service, datastore, or queue).
   • 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.

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 rename based on an entity’s tags.

1. If tag values follow a pattern, apply a regular expression to extract only the portion you want in the name.
2. If you’re correlating a service with infrastructure tags, choose one of the suggested infrastructure tags for the selected service.

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.

Remapping rules behavior

Services with remapping rules appear with consistent names across APM, Software Catalog, Logs, and Metrics.

• 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.
• 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.
• Service overrides: Remapping rules apply to base services; service overrides are not renamed.