Skip to content

Unified Service Tagging cleanup for KSM, global env, version #36678

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
janine-c merged 6 commits into from
May 15, 2026
+75 −116
Merged

Unified Service Tagging cleanup for KSM, global env, version #36678

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e8e46a8
Remove KSM specific steps and cleanup k8s basic handling
JacksonDavenport May 13, 2026
70142a8
Add global env level info to k8s
JacksonDavenport May 13, 2026
1865c2e
Consolidate container image version tagging outside of tabs
JacksonDavenport May 13, 2026
1ed6b72
Apply suggestions from code review
JacksonDavenport May 14, 2026
d6a6261
Add further recommendations
JacksonDavenport May 14, 2026
ed2c3d9
Clarify the labels and env var handling
JacksonDavenport May 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 75 additions & 116 deletions content/en/getting_started/tagging/unified_service_tagging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
**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 [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
Expand Down Expand Up @@ -79,11 +79,17 @@
{{< 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 in Kubernetes, add the following labels to both the parent workload and the pod template.
Copy link
Copy Markdown
Contributor

@janine-c janine-c May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find the use of "following" here confusing, because we don't list the labels; we talk about environment variables instead. Can we clarify the relationship between them?

Copy link
Copy Markdown
Contributor Author

@JacksonDavenport JacksonDavenport May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adjusted a bit and added those labels, but not sure if it looks too lengthy. But does that look more clear?

In general the labels are for the infrastructure side (metrics, logs, pod/container tagging) where as the env vars are largely just used by the Datadog tracers for the traces and spans.


- `tags.datadoghq.com/env: "<ENV>"`
- `tags.datadoghq.com/service: "<SERVICE>"`
- `tags.datadoghq.com/version: "<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
Expand All @@ -93,28 +99,29 @@
tags.datadoghq.com/env: "<ENV>"
tags.datadoghq.com/service: "<SERVICE>"
tags.datadoghq.com/version: "<VERSION>"
...
template:
metadata:
labels:
tags.datadoghq.com/env: "<ENV>"
tags.datadoghq.com/service: "<SERVICE>"
tags.datadoghq.com/version: "<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: "<ENV>"
tags.datadoghq.com/service: "<SERVICE>"
tags.datadoghq.com/version: "<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:
Expand All @@ -130,11 +137,35 @@
```
<div class="alert alert-danger">The <code>OTEL_SERVICE_NAME</code> environment variable takes precedence over the <code>service.name</code> attribute in the <code>OTEL_RESOURCE_ATTRIBUTES</code> environment variable.</div>

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.

Check notice on line 145 in content/en/getting_started/tagging/unified_service_tagging.md

View workflow job for this annotation

GitHub Actions / vale

Datadog.sentencelength 

Suggestion: Try to keep your sentence length to 25 words or fewer.

With the Datadog Operator:
```yaml
#(...)
spec:
global:
tags:
- "env:<ENV>"
```

With the Datadog Helm Chart:
```yaml
datadog:
#(...)
tags:
- "env:<ENV>"
```

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.

Check notice on line 164 in content/en/getting_started/tagging/unified_service_tagging.md

View workflow job for this annotation

GitHub Actions / vale

Datadog.sentencelength 

Suggestion: Try to keep your sentence length to 25 words or fewer.

###### 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:
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:
Expand All @@ -144,41 +175,15 @@
tags.datadoghq.com/service: "<SERVICE>"
tags.datadoghq.com/version: "<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/<container-name>.env
tags.datadoghq.com/<container-name>.service
tags.datadoghq.com/<container-name>.version
tags.datadoghq.com/<CONTAINER_NAME>.env
tags.datadoghq.com/<CONTAINER_NAME>.service
tags.datadoghq.com/<CONTAINER_NAME>.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: "<ENV>"
tags.datadoghq.com/service: "<SERVICE>"
tags.datadoghq.com/version: "<VERSION>"
spec:
template:
metadata:
labels:
tags.datadoghq.com/env: "<ENV>"
tags.datadoghq.com/service: "<SERVICE>"
tags.datadoghq.com/version: "<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:
Expand All @@ -195,41 +200,18 @@
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']
```

##### Automatic version tagging for APM data in containerized environments

<div class="alert alert-info">This feature is only enabled for <a href="https://docs.datadoghq.com/tracing/">Application Performance Monitoring (APM)</a> data.</div>

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 %}}

Expand Down Expand Up @@ -278,30 +260,6 @@

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

<div class="alert alert-info">This feature is only enabled for <a href="/tracing/">Application Performance Monitoring (APM)</a> data.</div>

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" %}}
Expand Down Expand Up @@ -352,11 +310,14 @@
}
```

{{% /tab %}}
{{% /tabs %}}

##### Automatic version tagging for APM data in containerized environments

<div class="alert alert-info">This feature is only enabled for <a href="/tracing/">Application Performance Monitoring (APM)</a> data.</div>

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.

Expand All @@ -369,14 +330,7 @@
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 to include the Git SHA, [embed Git information in your build artifacts][20].

### Non-containerized environment

Expand Down Expand Up @@ -589,3 +543,8 @@
[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
[21]: /containers/docker/log
[22]: /containers/kubernetes/log
Loading