--- title: Service remapping rules description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > APM > Service Observability > Service remapping rules --- # Service remapping rules {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} ## Overview{% #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. {% alert level="info" %} Each organization can contain up to 100 remapping rules. {% /alert %} ## Prerequisites{% #prerequisites %} You must have the `apm_service_renaming_write` permission to create remapping rules. See [Permissions](https://docs.datadoghq.com/account_management/rbac/permissions.md) for details on Datadog role-based access control. ### Tracer version requirements{% #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. | Language | Minimum supported tracer version | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | C++ | All versions supported | | Dotnet | [3.4.0](https://github.com/DataDog/dd-trace-dotnet/releases/tag/v3.4.0) | | Go | [1.55.0](https://github.com/DataDog/dd-trace-go/releases/tag/v1.55.0) | | Java | [1.20.0](https://github.com/DataDog/dd-trace-java/releases/tag/v1.20.0) | | JavaScript | [3.37.0](https://github.com/DataDog/dd-trace-js/releases/tag/v3.37.0)-3.x or [4.16.0](https://github.com/DataDog/dd-trace-js/releases/tag/v4.16.0) | | PHP | [0.94.1](https://github.com/DataDog/dd-trace-php/releases/tag/0.94.1) | | Python | [1.19.0](https://github.com/DataDog/dd-trace-py/releases/tag/v1.19.0) | | Ruby | [1.15.0](https://github.com/DataDog/dd-trace-rb/releases/tag/v1.15.0) | ## Create a service remapping rule{% #create-a-service-remapping-rule %} ### Step 1: Select remapping action and entities to target{% #step-1-select-remapping-action-and-entities-to-target %} 1. In Datadog, navigate to **APM** > **Catalog** > **Manage** > [**Service Remapping**](https://app.datadoghq.com/software/settings/service-rename). 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**](https://app.datadoghq.com/software) and click on a service to open the service side panel. From there, click **Service Page** > **Service Remapping**. {% image source="https://docs.dd-static.net/images/tracing/services/renaming_rules/service-side-panel.41c140a9d03535155d3a75b1f54f3a85.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/services/renaming_rules/service-side-panel.41c140a9d03535155d3a75b1f54f3a85.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The side panel for a service, showing the Service Page dropdown menu with a Service Remapping option" /%} 1. 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. 1. 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{% #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{% #step-3-name-your-rule-and-review %} 1. Optionally, enter a descriptive name for the remapping rule so you can identify it later. 1. 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-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](https://docs.datadoghq.com/tracing/services/service_override_removal.md) 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 1. Service defined in code (`tracer.Start(WithService(xx))`) 1. Service defined in the system property (`-Ddd.service={}`) 1. Service defined in the environment variable (`DD_SERVICE`) 1. Service defined in the config file (`application_monitoring.yaml`)