From e8e46a860aca05f08f0d68370df2166824646230 Mon Sep 17 00:00:00 2001 From: JacksonDavenport Date: Wed, 13 May 2026 14:56:14 -0700 Subject: [PATCH 1/6] Remove KSM specific steps and cleanup k8s basic handling --- .../tagging/unified_service_tagging.md | 89 +++++++------------ 1 file changed, 33 insertions(+), 56 deletions(-) diff --git a/content/en/getting_started/tagging/unified_service_tagging.md b/content/en/getting_started/tagging/unified_service_tagging.md index ce95098cc98..7f0e31db9eb 100644 --- a/content/en/getting_started/tagging/unified_service_tagging.md +++ b/content/en/getting_started/tagging/unified_service_tagging.md @@ -30,7 +30,7 @@ With these three tags, you can: **Notes**: - The `version` tag is expected to change with each new application deployment. Two different versions of your application's code should have distinct `version` tags. -- The official service of a log defaults to the container short-image if no Autodiscovery logs configuration is present. To override the official service of a log, add Autodiscovery [Docker labels/pod annotations][2]. For example: `"com.datadoghq.ad.logs"='[{"service": "service-name"}]'` +- The official `service` of a log defaults to the container short-image if no Autodiscovery logs configuration is present. To override the official `service` of a log, use the Unified Service Tagging options below or add a full custom Autodiscovery log configuration. - Host information is excluded for database and cache spans because the host associated with the span is not the database/cache host. ### Requirements @@ -79,11 +79,11 @@ To setup unified service tagging in a containerized environment: {{< tabs >}} {{% tab "Kubernetes" %}} -If you deployed the Datadog Cluster Agent with [Admission Controller][1] enabled, the Admission Controller mutates the pod manifests and injects all required environment variables (based on configured mutation conditions). In that case, manual configuration of `DD_` environment variables in pod manifests is unnecessary. For more information, see the [Admission Controller documentation][1]. - ##### Full configuration -To get the full range of unified service tagging when using Kubernetes, add environment variables to both the deployment object level and the pod template spec level: +To get the full range of unified service tagging when using Kubernetes, add the labels to both the parent workload level and the pod template level. + +The `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables are used by APM enabled applications. These environemnt variables can be set manually or by the [Kubernetes's downward API][2] as seen below. If you are using the Cluster Agent's [Admission Controller][1] to mutate your pods, those three environment variables are automatically injected to match your pod labels. ```yaml apiVersion: apps/v1 @@ -93,28 +93,29 @@ metadata: tags.datadoghq.com/env: "" tags.datadoghq.com/service: "" tags.datadoghq.com/version: "" -... -template: - metadata: - labels: - tags.datadoghq.com/env: "" - tags.datadoghq.com/service: "" - tags.datadoghq.com/version: "" - containers: - - ... - env: - - name: DD_ENV - valueFrom: - fieldRef: - fieldPath: metadata.labels['tags.datadoghq.com/env'] - - name: DD_SERVICE - valueFrom: - fieldRef: - fieldPath: metadata.labels['tags.datadoghq.com/service'] - - name: DD_VERSION - valueFrom: - fieldRef: - fieldPath: metadata.labels['tags.datadoghq.com/version'] +# (...) +spec: + template: + metadata: + labels: + tags.datadoghq.com/env: "" + tags.datadoghq.com/service: "" + tags.datadoghq.com/version: "" + containers: + - # (...) + env: + - name: DD_ENV + valueFrom: + fieldRef: + fieldPath: metadata.labels['tags.datadoghq.com/env'] + - name: DD_SERVICE + valueFrom: + fieldRef: + fieldPath: metadata.labels['tags.datadoghq.com/service'] + - name: DD_VERSION + valueFrom: + fieldRef: + fieldPath: metadata.labels['tags.datadoghq.com/version'] ``` You can also use the OpenTelemetry Resource Attributes environment variables to set the `env`, `service`, and `version` tags: @@ -130,11 +131,13 @@ You can also use the OpenTelemetry Resource Attributes environment variables to ```
The OTEL_SERVICE_NAME environment variable takes precedence over the service.name attribute in the OTEL_RESOURCE_ATTRIBUTES environment variable.
+These labels cover Kubernetes CPU, memory, network, and disk metrics. As well as general container tagging and log collection. These labels are also used by the Cluster Agent and its reported [Kubernetes State Metrics][3]. + ##### Partial configuration ###### Pod-level metrics -To configure pod-level metrics, add the following standard labels (`tags.datadoghq.com`) to the pod spec of a Deployment, StatefulSet, or Job: +If you are not using APM in your applications you can omit the `DD_ENV`, `DD_SERVICE`, `DD_VERSION` environment variables. Just adding the following standard labels (`tags.datadoghq.com`) to the pod spec as well as optionally to the parent workload like the Deployment, StatefulSet, or Job: ```yaml template: @@ -144,41 +147,15 @@ template: tags.datadoghq.com/service: "" tags.datadoghq.com/version: "" ``` -These labels cover pod-level Kubernetes CPU, memory, network, and disk metrics, and can be used for injecting `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` into your service's container through [Kubernetes's downward API][2]. If you have multiple containers per pod, you can specify standard labels by container: ```yaml -tags.datadoghq.com/.env -tags.datadoghq.com/.service -tags.datadoghq.com/.version +tags.datadoghq.com/.env +tags.datadoghq.com/.service +tags.datadoghq.com/.version ``` -###### State metrics - -To configure [Kubernetes State Metrics][3]: - -1. Set `join_standard_tags` to `true` in your configuration file. See this [example configuration file][4] for the setting location. - -2. Add the same standard labels to the collection of labels for the parent resource, for example: `Deployment`. - - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - labels: - tags.datadoghq.com/env: "" - tags.datadoghq.com/service: "" - tags.datadoghq.com/version: "" - spec: - template: - metadata: - labels: - tags.datadoghq.com/env: "" - tags.datadoghq.com/service: "" - tags.datadoghq.com/version: "" - ``` - ###### Datadog SDK and StatsD client To configure [Datadog SDK][5] and [StatsD client][6] environment variables, use the [Kubernetes's downward API][2] in the format below: From 70142a88f03542715b4bef56252f04650ca06761 Mon Sep 17 00:00:00 2001 From: JacksonDavenport Date: Wed, 13 May 2026 15:12:06 -0700 Subject: [PATCH 2/6] Add global env level info to k8s --- .../tagging/unified_service_tagging.md | 56 +++++++++++++------ 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/content/en/getting_started/tagging/unified_service_tagging.md b/content/en/getting_started/tagging/unified_service_tagging.md index 7f0e31db9eb..7f417ea72a4 100644 --- a/content/en/getting_started/tagging/unified_service_tagging.md +++ b/content/en/getting_started/tagging/unified_service_tagging.md @@ -83,7 +83,7 @@ To setup unified service tagging in a containerized environment: To get the full range of unified service tagging when using Kubernetes, add the labels to both the parent workload level and the pod template level. -The `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables are used by APM enabled applications. These environemnt variables can be set manually or by the [Kubernetes's downward API][2] as seen below. If you are using the Cluster Agent's [Admission Controller][1] to mutate your pods, those three environment variables are automatically injected to match your pod labels. +The `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables are used by APM enabled applications. These environment variables can be set manually or by the [Kubernetes's downward API][2] as seen below. If you are using the Cluster Agent's [Admission Controller][1] to mutate your pods, those three environment variables are automatically injected to match your labels. ```yaml apiVersion: apps/v1 @@ -104,18 +104,18 @@ spec: containers: - # (...) env: - - name: DD_ENV - valueFrom: - fieldRef: - fieldPath: metadata.labels['tags.datadoghq.com/env'] - - name: DD_SERVICE - valueFrom: - fieldRef: - fieldPath: metadata.labels['tags.datadoghq.com/service'] - - name: DD_VERSION - valueFrom: - fieldRef: - fieldPath: metadata.labels['tags.datadoghq.com/version'] + - name: DD_ENV + valueFrom: + fieldRef: + fieldPath: metadata.labels['tags.datadoghq.com/env'] + - name: DD_SERVICE + valueFrom: + fieldRef: + fieldPath: metadata.labels['tags.datadoghq.com/service'] + - name: DD_VERSION + valueFrom: + fieldRef: + fieldPath: metadata.labels['tags.datadoghq.com/version'] ``` You can also use the OpenTelemetry Resource Attributes environment variables to set the `env`, `service`, and `version` tags: @@ -135,9 +135,31 @@ These labels cover Kubernetes CPU, memory, network, and disk metrics. As well as ##### Partial configuration +###### Global env handling +If your Kubernetes cluster is entirely a single environment, for example only `env:production` nodes and workloads, you can provide this to your Agent configuration rather than tagging each workload individually. + +With the Datadog Operator: +```yaml +#(...) +spec: + global: + tags: + - "env:" +``` + +With the Datadog Helm Chart: +```yaml +datadog: + #(...) + tags: + - "env:" +``` + +This will establish this as a host level tag inherited on all your data associated with each host. This will also be applied to all [Kubernetes State Metrics][3] and be the default `env` on your APM spans. Take care with these tags as if you have a global `env` tag set and a *different* `env` tag set on your pod, that pod's data will have both `env` tags present. + ###### Pod-level metrics -If you are not using APM in your applications you can omit the `DD_ENV`, `DD_SERVICE`, `DD_VERSION` environment variables. Just adding the following standard labels (`tags.datadoghq.com`) to the pod spec as well as optionally to the parent workload like the Deployment, StatefulSet, or Job: +If you are not using APM in your applications you can omit the `DD_ENV`, `DD_SERVICE`, `DD_VERSION` environment variables. Add the following standard labels (`tags.datadoghq.com`) to the pod spec as well as optionally to the parent workload like the Deployment, StatefulSet, or Job: ```yaml template: @@ -172,9 +194,9 @@ containers: valueFrom: fieldRef: fieldPath: metadata.labels['tags.datadoghq.com/service'] - - name: DD_VERSION - valueFrom: - fieldRef: + - name: DD_VERSION + valueFrom: + fieldRef: fieldPath: metadata.labels['tags.datadoghq.com/version'] ``` From 1865c2eddc11db524a3f5b7107770f08534e06c0 Mon Sep 17 00:00:00 2001 From: JacksonDavenport Date: Wed, 13 May 2026 16:27:35 -0700 Subject: [PATCH 3/6] Consolidate container image version tagging outside of tabs --- .../tagging/unified_service_tagging.md | 66 +++---------------- 1 file changed, 9 insertions(+), 57 deletions(-) diff --git a/content/en/getting_started/tagging/unified_service_tagging.md b/content/en/getting_started/tagging/unified_service_tagging.md index 7f417ea72a4..bcd7f1eabcd 100644 --- a/content/en/getting_started/tagging/unified_service_tagging.md +++ b/content/en/getting_started/tagging/unified_service_tagging.md @@ -200,35 +200,12 @@ containers: fieldPath: metadata.labels['tags.datadoghq.com/version'] ``` -##### Automatic version tagging for APM data in containerized environments - -
This feature is only enabled for Application Performance Monitoring (APM) data.
- -You can use the `version` tag in APM to [monitor deployments][7] and to identify faulty code deployments through [Automatic Faulty Deployment Detection][8]. - -For APM data, Datadog sets the `version` tag for you in the following priority order. If you manually set `version`, Datadog does not override your `version` value. - -| Priority | Version Value | -|--------------|------------| -| 1 | {your version value} | -| 2 | {image_tag}_{first_7_digits_of_git_commit_sha} | -| 3 | {image_tag} or {first_7_digits_of_git_commit_sha} if only one is available | - -Requirements: -- Datadog Agent Version 7.52.0 or greater -- If your services run in a containerized environment and `image_tag` is sufficient for tracking new version deployments, no further configuration is needed. -- If your services are not running in a containerized environment, or if you'd also like to have the Git SHA included, [embed Git information in your build artifacts][9]. - - [1]: /agent/cluster_agent/admission_controller/ [2]: https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/#capabilities-of-the-downward-api -[3]: /agent/kubernetes/data_collected/#kube-state-metrics +[3]: /integrations/kubernetes_state_core/?tab=helm#data-collected [4]: https://github.com/DataDog/integrations-core/blob/master/kubernetes_state/datadog_checks/kubernetes_state/data/conf.yaml.example [5]: /tracing/send_traces/ [6]: /integrations/statsd/ -[7]: /tracing/services/deployment_tracking/ -[8]: /watchdog/faulty_deployment_detection/ -[9]: /integrations/guide/source-code-integration/?tab=go#embed-git-information-in-your-build-artifacts {{% /tab %}} @@ -277,30 +254,6 @@ com.datadoghq.tags.version As explained in the full configuration, these labels can be set in a Dockerfile or as arguments for launching the container. -##### Automatic version tagging for APM data in containerized environments - -
This feature is only enabled for Application Performance Monitoring (APM) data.
- -You can use the `version` tag in APM to [monitor deployments][1] and to identify faulty code deployments through [Automatic Faulty Deployment Detection][2]. - -For APM data, Datadog sets the `version` tag for you in the following priority order. If you manually set `version`, Datadog does not override your `version` value. - -| Priority | Version Value | -|--------------|------------| -| 1 | {your version value} | -| 2 | {image_tag}_{first_7_digits_of_git_commit_sha} | -| 3 | {image_tag} or {first_7_digits_of_git_commit_sha} if only one is available | - -Requirements: -- Datadog Agent Version 7.52.0 or greater -- If your services run in a containerized environment and `image_tag` is sufficient for tracking new version deployments, no further configuration is needed. -- If your services are not running in a containerized environment, or if you'd also like to have the Git SHA included, [embed Git information in your build artifacts][3]. - - -[1]: /tracing/services/deployment_tracking/ -[2]: /watchdog/faulty_deployment_detection/ -[3]: /integrations/guide/source-code-integration/?tab=go#embed-git-information-in-your-build-artifacts - {{% /tab %}} {{% tab "ECS" %}} @@ -351,11 +304,14 @@ If your service has no need for the Datadog environment variables (for example, } ``` +{{% /tab %}} +{{% /tabs %}} + ##### Automatic version tagging for APM data in containerized environments
This feature is only enabled for Application Performance Monitoring (APM) data.
-You can use the `version` tag in APM to [monitor deployments][1] and to identify faulty code deployments through [Automatic Faulty Deployment Detection][2]. +You can use the `version` tag in APM to [monitor deployments][18] and to identify faulty code deployments through [Automatic Faulty Deployment Detection][19]. For APM data, Datadog sets the `version` tag for you in the following priority order. If you manually set `version`, Datadog does not override your `version` value. @@ -368,14 +324,7 @@ For APM data, Datadog sets the `version` tag for you in the following priority o Requirements: - Datadog Agent Version 7.52.0 or greater - If your services run in a containerized environment and `image_tag` is sufficient for tracking new version deployments, no further configuration is needed. -- If your services are not running in a containerized environment, or if you'd also like to have the Git SHA included, [embed Git information in your build artifacts][3]. - -[1]: /tracing/services/deployment_tracking/ -[2]: /watchdog/faulty_deployment_detection/ -[3]: /integrations/guide/source-code-integration/?tab=go#embed-git-information-in-your-build-artifacts - -{{% /tab %}} -{{% /tabs %}} +- If your services are not running in a containerized environment, or if you'd also like to have the Git SHA included, [embed Git information in your build artifacts][20]. ### Non-containerized environment @@ -588,3 +537,6 @@ processors: [15]: /serverless/configuration/#connect-telemetry-using-tags [16]: https://opentelemetry.io/docs/languages/js/resources/ [17]: https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.27.0 +[18]: /tracing/services/deployment_tracking/ +[19]: /watchdog/faulty_deployment_detection/ +[20]: /integrations/guide/source-code-integration/?tab=go#embed-git-information-in-your-build-artifacts \ No newline at end of file From 1ed6b72592c0f6d842fb884fd509c5049d0094d1 Mon Sep 17 00:00:00 2001 From: Jackson Davenport Date: Thu, 14 May 2026 14:57:30 -0700 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Janine Chan <64388808+janine-c@users.noreply.github.com> --- .../getting_started/tagging/unified_service_tagging.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/getting_started/tagging/unified_service_tagging.md b/content/en/getting_started/tagging/unified_service_tagging.md index bcd7f1eabcd..de8c1013b6e 100644 --- a/content/en/getting_started/tagging/unified_service_tagging.md +++ b/content/en/getting_started/tagging/unified_service_tagging.md @@ -131,12 +131,12 @@ You can also use the OpenTelemetry Resource Attributes environment variables to ```
The OTEL_SERVICE_NAME environment variable takes precedence over the service.name attribute in the OTEL_RESOURCE_ATTRIBUTES environment variable.
-These labels cover Kubernetes CPU, memory, network, and disk metrics. As well as general container tagging and log collection. These labels are also used by the Cluster Agent and its reported [Kubernetes State Metrics][3]. +These labels cover Kubernetes CPU, memory, network, and disk metrics, as well as general container tagging and log collection. These labels are also used by the Cluster Agent and its reported [Kubernetes State Metrics][3]. ##### Partial configuration ###### Global env handling -If your Kubernetes cluster is entirely a single environment, for example only `env:production` nodes and workloads, you can provide this to your Agent configuration rather than tagging each workload individually. +If your Kubernetes cluster is entirely a single environment, for example, only `env:production` nodes and workloads, you can provide this to your Agent configuration rather than tagging each workload individually. With the Datadog Operator: ```yaml @@ -155,11 +155,11 @@ datadog: - "env:" ``` -This will establish this as a host level tag inherited on all your data associated with each host. This will also be applied to all [Kubernetes State Metrics][3] and be the default `env` on your APM spans. Take care with these tags as if you have a global `env` tag set and a *different* `env` tag set on your pod, that pod's data will have both `env` tags present. +This establishes this as a host-level tag inherited on all your data associated with each host. This is also applied to all [Kubernetes State Metrics][3] and is the default `env` on your APM spans. Take care with these tags, as if you have a global `env` tag set and a *different* `env` tag set on your pod, that pod's data contains **both** `env` tags. ###### Pod-level metrics -If you are not using APM in your applications you can omit the `DD_ENV`, `DD_SERVICE`, `DD_VERSION` environment variables. Add the following standard labels (`tags.datadoghq.com`) to the pod spec as well as optionally to the parent workload like the Deployment, StatefulSet, or Job: +The `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables are only required if you are using APM in your applications; otherwise, you can omit them. Add the following standard labels (`tags.datadoghq.com`) to the pod spec, as well as optionally to the parent workload, like the Deployment, StatefulSet, or Job: ```yaml template: @@ -324,7 +324,7 @@ For APM data, Datadog sets the `version` tag for you in the following priority o Requirements: - Datadog Agent Version 7.52.0 or greater - If your services run in a containerized environment and `image_tag` is sufficient for tracking new version deployments, no further configuration is needed. -- If your services are not running in a containerized environment, or if you'd also like to have the Git SHA included, [embed Git information in your build artifacts][20]. +- If your services are not running in a containerized environment, or to include the Git SHA, [embed Git information in your build artifacts][20]. ### Non-containerized environment From d6a6261fcc70762ac0bf2e1bfb105525cf9a8b9b Mon Sep 17 00:00:00 2001 From: JacksonDavenport Date: Thu, 14 May 2026 15:24:58 -0700 Subject: [PATCH 5/6] Add further recommendations --- .../getting_started/tagging/unified_service_tagging.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/content/en/getting_started/tagging/unified_service_tagging.md b/content/en/getting_started/tagging/unified_service_tagging.md index de8c1013b6e..d9d2ced593a 100644 --- a/content/en/getting_started/tagging/unified_service_tagging.md +++ b/content/en/getting_started/tagging/unified_service_tagging.md @@ -30,7 +30,7 @@ With these three tags, you can: **Notes**: - The `version` tag is expected to change with each new application deployment. Two different versions of your application's code should have distinct `version` tags. -- The official `service` of a log defaults to the container short-image if no Autodiscovery logs configuration is present. To override the official `service` of a log, use the Unified Service Tagging options below or add a full custom Autodiscovery log configuration. +- The official `service` of a log defaults to the container short-image if no Autodiscovery logs configuration is present. To override the official `service` of a log, use the Unified Service Tagging options below or add a full custom [Docker][21] or [Kubernetes][22] Autodiscovery log configuration. - Host information is excluded for database and cache spans because the host associated with the span is not the database/cache host. ### Requirements @@ -81,9 +81,9 @@ To setup unified service tagging in a containerized environment: ##### Full configuration -To get the full range of unified service tagging when using Kubernetes, add the labels to both the parent workload level and the pod template level. +To get the full range of unified service tagging in Kubernetes, add the following labels to both the parent workload and the pod template. -The `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables are used by APM enabled applications. These environment variables can be set manually or by the [Kubernetes's downward API][2] as seen below. If you are using the Cluster Agent's [Admission Controller][1] to mutate your pods, those three environment variables are automatically injected to match your labels. +The `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables are used by APM-enabled applications. You can set these environment variables manually or using the [Kubernetes's downward API][2] as seen below. If you are using the Cluster Agent's [Admission Controller][1] to mutate your pods, those three environment variables are automatically injected to match your labels. ```yaml apiVersion: apps/v1 @@ -539,4 +539,6 @@ processors: [17]: https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.27.0 [18]: /tracing/services/deployment_tracking/ [19]: /watchdog/faulty_deployment_detection/ -[20]: /integrations/guide/source-code-integration/?tab=go#embed-git-information-in-your-build-artifacts \ No newline at end of file +[20]: /integrations/guide/source-code-integration/?tab=go#embed-git-information-in-your-build-artifacts +[21]: /containers/docker/log +[22]: /containers/kubernetes/log \ No newline at end of file From ed2c3d9cba62a5d3b7ee56de7fc49d8faac6e2d6 Mon Sep 17 00:00:00 2001 From: JacksonDavenport Date: Fri, 15 May 2026 10:47:42 -0700 Subject: [PATCH 6/6] Clarify the labels and env var handling --- .../en/getting_started/tagging/unified_service_tagging.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/content/en/getting_started/tagging/unified_service_tagging.md b/content/en/getting_started/tagging/unified_service_tagging.md index d9d2ced593a..0f5200e658b 100644 --- a/content/en/getting_started/tagging/unified_service_tagging.md +++ b/content/en/getting_started/tagging/unified_service_tagging.md @@ -83,7 +83,13 @@ To setup unified service tagging in a containerized environment: To get the full range of unified service tagging in Kubernetes, add the following labels to both the parent workload and the pod template. -The `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` environment variables are used by APM-enabled applications. You can set these environment variables manually or using the [Kubernetes's downward API][2] as seen below. If you are using the Cluster Agent's [Admission Controller][1] to mutate your pods, those three environment variables are automatically injected to match your labels. +- `tags.datadoghq.com/env: ""` +- `tags.datadoghq.com/service: ""` +- `tags.datadoghq.com/version: "" ` + +For APM-enabled applications additionally set the environment variables `DD_ENV`, `DD_SERVICE`, and `DD_VERSION` for the Datadog tracers. + +You can set these environment variables manually or with the [Kubernetes's downward API][2]. If you are using the Cluster Agent's [Admission Controller][1] to mutate your pods, those three environment variables are automatically injected to match your labels. ```yaml apiVersion: apps/v1