diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index 8554b35541b..8b507a4548c 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -4434,11 +4434,16 @@ menu: parent: tracing_services identifier: tracing_service_remapping_rules weight: 908 + - name: Service Override Removal + url: tracing/services/service_override_removal + parent: tracing_services + identifier: tracing_service_override_removal + weight: 909 - name: APM Monitors url: /monitors/create/types/apm/ parent: tracing_services identifier: tracing_apm_monitors - weight: 909 + weight: 910 - name: Endpoint Observability url: internal_developer_portal/software_catalog/endpoints/ identifier: endpoint_observability diff --git a/content/en/tracing/guide/service_overrides.md b/content/en/tracing/guide/service_overrides.md index 7f8b6011758..c705fdee4c2 100644 --- a/content/en/tracing/guide/service_overrides.md +++ b/content/en/tracing/guide/service_overrides.md @@ -3,6 +3,9 @@ title: Service Overrides description: Understand service overrides and how to adapt your configuration when using inferred services to improve service dependency representation. disable_toc: false further_reading: +- link: "/tracing/services/service_override_removal" + tag: "Documentation" + text: "Remove Service Overrides" - link: "/tracing/services/inferred_services" tag: "Documentation" text: "Inferred services" @@ -75,59 +78,7 @@ In the trace side panel, the client span header represents the call going from t ## Remove service overrides -To remove *integration service overrides*, set the environment variable: - -```sh -DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED=true -``` - -This ensures the `service` attribute always uses the base service name instead of appending the integration name (for example,`*-postgres`, `*-http-client`). - -
Removing service overrides is a breaking change. Metrics, monitors, or dashboard queries based on the overridden service name will stop matching.
- -It is recommended to remove service overrides progressively, proceeding service by service, to ensure that no critical assets (such as dashboards, monitors, retention filters, and so on) are affected by the change. Follow the [detailed instructions](#remove-service-overrides-progressively) to ensure a smooth transition to the new model. - -### Examples - -For example: - -- .NET tags gRPC calls as `service:-grpc-client` -- Python tags gRPC calls as `service:grpc-client` - -With the `DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED` option set to `true`, all supported tracing libraries tag client spans capturing the call to the downstream service with the calling service's name, `service:`. This ensures all spans are always tagged with the *default service name* emitting the span; [`peer.*`][6] attributes are used to describe the called dependency (for example, database or queue). - -| Scenario | Service Name | Additional `peer.*` Attributes | -|----------|--------------|--------------------------------| -| *Without* inferred services and *with* service overrides | `service:my-service-grpc-client` or `service:grpc-client` | No `peer.*` attributes set | -| *With* inferred services and *without* service overrides | `service:myservice` | `@peer.service:otherservice` (where `otherservice` is the name of the remote service being called with gRPC) | - -Similarly, for a span representing a call to a mySQL database: - -| Scenario | Service Name | Additional `peer.*` Attributes | -|----------|--------------|--------------------------------| -| *Without* inferred services and *with* service overrides | `service:my-service-mysql` or `service:mysql` | No `peer.*` tags set | -| *With* inferred services and *without* service overrides | `service:myservice` | `@peer.db.name:user-db`, `@peer.db.system:mysql` | - -### Remove service overrides progressively - -1. Identify the service override you want to remove and navigate to its **service page**. -2. Hover over the service override pill in the page header and note the underlying base service names. These are the original services emitting spans with overrides. You need to update the configuration for these instrumented services. - -{{< img src="/tracing/guide/service_overrides/service_overrides_service_page.png" alt="Service page overrides" style="width:70%;">}} - -3. Scan through your existing assets that might contain queries using the override service name: - - - Any monitors, dashboards, or notebooks queries based on [APM Trace metrics][5] - - [APM metrics from spans][2] - - [Trace analytics monitors][3] (based on indexed spans) - - [Retention filters][4] - - Sensitive data scanner pipelines - -4. Update these queries to use the base service name (`service:`). This allows queries to continue to match when you remove service overrides - -5. Set `DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED=true` for integration service overrides. - -**Note**: The configuration above only removes [integration service overrides](#integration-service-overrides). Custom service overrides must be removed directly in the code. +With inferred services, integration service overrides are no longer necessary and may clutter your service maps. You can remove them directly in Datadog. For step-by-step instructions, see [Service Override Removal][2]. ## Glossary @@ -142,8 +93,4 @@ The default `DD_SERVICE` name. {{< partial name="whats-next/whats-next.html" >}} [1]: /tracing/services/inferred_services -[2]: /tracing/trace_pipeline/generate_metrics -[3]: /monitors/types/apm/?tab=traceanalytics -[4]: /tracing/trace_pipeline/trace_retention/#retention-filters -[5]: /tracing/metrics/metrics_namespace/ -[6]: /tracing/services/inferred_services/#peer-tags +[2]: /tracing/services/service_override_removal diff --git a/content/en/tracing/services/service_override_removal.md b/content/en/tracing/services/service_override_removal.md new file mode 100644 index 00000000000..28fea55d116 --- /dev/null +++ b/content/en/tracing/services/service_override_removal.md @@ -0,0 +1,101 @@ +--- +title: Service Override Removal +description: Learn how to remove integration service overrides from Datadog. +disable_toc: false +further_reading: +- link: "/tracing/guide/service_overrides" + tag: "Documentation" + text: "Service Overrides" +- link: "/tracing/services/inferred_services" + tag: "Documentation" + text: "Inferred Services" +--- + +This page explains how to remove integration service overrides, which use integration-specific service names to represent calls to other services. For conceptual background, see [Service Overrides][10] and [Inferred Services][8]. + +## Prerequisites + +Before you remove integration service overrides: + +1. You must have the `apm_service_renaming_write` permission. +1. Your Datadog SDK version must support override removal. See [SDK version requirements](#sdk-version-requirements). + +### SDK version requirements + +| Language | Minimum supported version | +|------------|---------------------------| +| .NET | [3.4.0][1] | +| Go | [1.55.0][2] | +| Java | [1.20.0][3] | +| Node.js | [4.16.0][4] | +| PHP | [0.94.1][5] | +| Python | [1.19.0][6] | +| Ruby | [1.15.0][7] | + +## Remove service overrides + +To remove service overrides in Datadog: + +1. Navigate to **Software Catalog** > **Manage** > [**Manage Remapping Rules**][12], and click **Manage Overrides**. + + {{< img src="tracing/guide/service_overrides/SO_removal_page.png" alt="Service Overrides page showing migration progress and removal options" style="width:100%;" >}} + +1. For each override you plan to remove, review the related monitors and dashboards. + + These assets reference the overridden service name and stop matching after removal. Update them to use the base service name (`service:`) to preserve functionality. + + {{< img src="tracing/guide/service_overrides/SO_removal_page_sidepanel.png" alt="Service override side panel showing affected monitors and dashboards" style="width:100%;" >}} + +1. Remove overrides individually or in bulk: + - **Select specific overrides to remove**: Choose individual integration service overrides to remove. A **Migration Progress** bar shows your progress as you remove overrides. This action is reversible. + - **Remove all overrides**: Select **Remove All Overrides** to permanently remove all integration service overrides and prevent future ones from appearing as APM usage increases. Custom service overrides are not affected. + +
Removing all integration service overrides is permanent and cannot be undone.
+ +## Examples: Service naming after removal + +Removing service overrides changes how client spans are tagged and how downstream dependencies are identified. After overrides are removed, client spans use the calling service's name (`service:`) instead of the integration-specific name. The called dependency is identified using [`peer.*` attributes][11] (for example, database or queue). + +**gRPC example:** + +| Scenario | Service name | Additional `peer.*` attributes | +|---------------------------|-----------------------------------------------------------|--------------------------------| +| With service overrides | `service:my-service-grpc-client` or `service:grpc-client` | None | +| Without service overrides | `service:myservice` | `@peer.service:otherservice` | + +**MySQL example:** + +| Scenario | Service name | Additional `peer.*` attributes | +|----------|--------------|--------------------------------| +| With service overrides | `service:my-service-mysql` or `service:mysql` | None | +| Without service overrides | `service:myservice` | `@peer.db.name:user-db`, `@peer.db.system:mysql` | + +## Configuration-based removal + +You can also remove integration service overrides by setting an environment variable in your application configuration. This approach is useful if you cannot access the Datadog UI. + +1. Confirm that your SDK meets the [minimum version requirements](#sdk-version-requirements). +2. Set the following environment variable: + ```sh + DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED=true + ``` + +This ensures the `service` attribute always uses the base service name instead of appending the integration name (for example, `*-postgres`, `*-http-client`). Custom service overrides are not affected and must be removed directly in your code. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://github.com/DataDog/dd-trace-dotnet/releases/tag/v3.4.0 +[2]: https://github.com/DataDog/dd-trace-go/releases/tag/v1.55.0 +[3]: https://github.com/DataDog/dd-trace-java/releases/tag/v1.20.0 +[4]: https://github.com/DataDog/dd-trace-js/releases/tag/v4.16.0 +[5]: https://github.com/DataDog/dd-trace-php/releases/tag/0.94.1 +[6]: https://github.com/DataDog/dd-trace-py/releases/tag/v1.19.0 +[7]: https://github.com/DataDog/dd-trace-rb/releases/tag/v1.15.0 +[8]: /tracing/services/inferred_services +[9]: https://app.datadoghq.com/apm/settings/service-naming +[10]: /tracing/guide/service_overrides +[11]: /tracing/services/inferred_services/#peer-tags +[12]: https://app.datadoghq.com/software/settings/service-remapping + diff --git a/static/images/tracing/guide/service_overrides/SO_removal_page.png b/static/images/tracing/guide/service_overrides/SO_removal_page.png new file mode 100644 index 00000000000..da9021d270e Binary files /dev/null and b/static/images/tracing/guide/service_overrides/SO_removal_page.png differ diff --git a/static/images/tracing/guide/service_overrides/SO_removal_page_sidepanel.png b/static/images/tracing/guide/service_overrides/SO_removal_page_sidepanel.png new file mode 100644 index 00000000000..abad51ba671 Binary files /dev/null and b/static/images/tracing/guide/service_overrides/SO_removal_page_sidepanel.png differ