diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index e066e57b82b..d3fa6ed721a 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -4454,16 +4454,21 @@ menu: parent: tracing_services identifier: tracing_service_remapping_rules weight: 908 + - name: Tag Enrichment + url: tracing/services/tag_enrichment + parent: tracing_services + identifier: tracing_tag_enrichment + weight: 909 - name: Integration Override Removal url: tracing/services/integration_override_removal parent: tracing_services identifier: tracing_service_override_removal - weight: 909 + weight: 910 - name: APM Monitors url: /monitors/create/types/apm/ parent: tracing_services identifier: tracing_apm_monitors - weight: 910 + weight: 911 - name: Endpoint Observability url: internal_developer_portal/software_catalog/endpoints/ identifier: endpoint_observability diff --git a/content/en/tracing/services/tag_enrichment.md b/content/en/tracing/services/tag_enrichment.md new file mode 100644 index 00000000000..bda9a0a9f0f --- /dev/null +++ b/content/en/tracing/services/tag_enrichment.md @@ -0,0 +1,69 @@ +--- +title: Tag Enrichment +description: Automatically enrich telemetry with team and system tags from Software Catalog service definitions without redeploying code. +further_reading: +- link: "/tracing/services/service_remapping_rules" + tag: "Documentation" + text: "Service remapping rules" +- link: "/internal_developer_portal/software_catalog/" + tag: "Documentation" + text: "Software Catalog" +--- + +{{< callout btn_hidden="true" >}} +Tag enrichment is in Preview. +{{< /callout >}} + +## Overview + +Use tag enrichment rules to add `team` and `system` tags to your APM spans without code changes or redeployment. Datadog automatically pulls tag values from service metadata you've already defined in Software Catalog. + +## Prerequisites + +You must have the Datadog Admin Role to create tag enrichment rules. See [Role-based access control][2] for details. + +## Create a tag enrichment rule + +### Default tag enrichment rules + +To enable a default rule, navigate to **IDP** > **Manage** > [**Tag Enrichment**][1] and toggle on the default rule for `team` or `system` at the bottom of the page. + +{{< img src="tracing/services/tag_enrichment/tag-enrichment-landing.png" alt="The Tag Enrichment page showing the Suggested rules panel, with options to create enrichment rules for system and team tags for all services." >}} + +Enabling a default rule applies `team` or `system` to all telemetry of services based on the Entity Metadata defined in IDP. Only services with Entity Metadata populated are enriched. Tags are added only when the service's telemetry does not already have a value for that tag. + +### Custom tag enrichment rules + +Custom rules let you target a specific set of services and configure exactly how each tag value is sourced and applied. + +1. In Datadog, navigate to **IDP** > **Manage** > [**Tag Enrichment**][1] and click **+ Add Rule**. +1. Select entities to enrich. As you select entities, a query is built in the background. To edit the query, select **Build Advanced Query**. + {{< img src="tracing/services/tag_enrichment/tag-enrichment-adv-query.png" alt="The Add IDP tag enrichment rule modal with the Build Advanced Query tab selected, showing fields for tag key, operator, and value, with an Add Condition option." >}} + - Select **Add Condition** to add an `AND` condition to your query. + - Add multiple values in the **Value** field to create an `OR` condition. +1. Choose tags and enrichment methods: + - Select the `team` tag, `system` tag, or both. + - For each tag, select whether the tag value comes from Entity Metadata, the value of a different tag, or a fixed value. + - Choose whether the value is applied only when it doesn't already exist, or is appended to the current list of values for that tag. +1. By default, tags are added to all telemetry. Select which telemetry types to enrich. +1. Optionally, enter a descriptive name for the rule. +1. Review and save your rule. After you save the rule, it can take up to an hour for enrichment to be fully applied to incoming telemetry. + +### Add a tag enrichment rule from a service page + +On any service page that is missing a `team` or `system` tag, click **Add Tags** on the top banner to enrich telemetry for that service. + +## Tag enrichment behavior + +- **Impacted telemetry**: Tag enrichment applies to APM spans only. +- **Historical data**: Tag enrichment rules apply only to telemetry ingested while a rule is active. Past data is not updated retroactively. Deleting or modifying a rule stops it from applying to new telemetry, but does not update previously ingested data. +- **Metadata updates**: Updating or adding Entity Metadata to services for `team` or `system` while an enrichment rule is enabled, including the default rule, automatically updates those tags. +- **Rule processing order**: Tag enrichment rules are applied in the order in which they were created. Rules at the top of the list take precedence over rules below them. +- **Interaction with remapping rules**: Tag enrichment rules are applied after service remapping rules. If a service remapping rule modifies the `service` tag, enrichment uses the updated service name when looking up IDP metadata. + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: https://app.datadoghq.com/software/settings/tag-enrichment +[2]: /account_management/rbac/ diff --git a/static/images/tracing/services/tag_enrichment/tag-enrichment-adv-query.png b/static/images/tracing/services/tag_enrichment/tag-enrichment-adv-query.png new file mode 100644 index 00000000000..d02db26f10c Binary files /dev/null and b/static/images/tracing/services/tag_enrichment/tag-enrichment-adv-query.png differ diff --git a/static/images/tracing/services/tag_enrichment/tag-enrichment-landing.png b/static/images/tracing/services/tag_enrichment/tag-enrichment-landing.png new file mode 100644 index 00000000000..386075e9a8d Binary files /dev/null and b/static/images/tracing/services/tag_enrichment/tag-enrichment-landing.png differ