Kubernetes OTel Integration #30815

brett0000FF · 2025-07-30T22:54:18Z

What does this PR do? What is the motivation?

Adds a new guide for monitoring Kubernetes clusters using the OpenTelemetry Collector. Based on opentelemetry-examples page.

Adds a new page at /opentelemetry/integrations/kubernetes_metrics.md.
Updates the main OTel integrations page (/opentelemetry/integrations.md) to include a link to the new guide under the "Containers and hosts" section.

Merge instructions

Merge readiness:

Ready for merge

For Datadog employees:

Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). Without this format, your pull request will not pass CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.

If your branch doesn't follow this format, rename it or create a new branch and PR.

[6/5/2025] Merge queue has been disabled on the documentation repo. If you have write access to the repo, the PR has been reviewed by a Documentation team member, and all of the required checks have passed, you can use the Squash and Merge button to merge the PR. If you don't have write access, or you need help, reach out in the #documentation channel in Slack.

Additional notes

github-actions · 2025-07-30T22:54:36Z

📝 Documentation Team Review Required

This pull request requires approval from the @DataDog/documentation team before it can be merged.

Please ensure your changes follow our documentation guidelines and wait for a team member to review and approve your changes.

github-actions · 2025-07-30T22:57:48Z

Preview links (active after the `build_preview` check completes)

New or renamed files

https://docs-staging.datadoghq.com/brett.blue/otel-k8s/opentelemetry/integrations/kubernetes_metrics

Modified Files

https://docs-staging.datadoghq.com/brett.blue/otel-k8s/opentelemetry/integrations/

janine-c

Looks great, Brett! I had some things I had some minor questions about, but nothing that would be a showstopper. Always open to chat further about things, or approve again if this one gets stale 🙂

content/en/opentelemetry/integrations/kubernetes_metrics.md

janine-c · 2025-08-06T22:23:53Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+### Prerequisites
+
+* **Helm**: The setup uses Helm to deploy resources. To install Helm, see the [official Helm documentation][2].
+* **Collector Image**: This guide uses the `otel/opentelemetry-collector-contrib:0.130.0` image or newer.


In context, should a user usually know which version of the collector image they're using? If not, maybe we could add a link where they could check/update it if necessary?

janine-c · 2025-08-06T22:29:30Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+
+3.  **Install the OpenTelemetry Collectors**
+
+    First, add the OpenTelemetry Helm chart repository:


I would recommend using a nested ordered list to indicate these substeps, just to make them easier to see 🙂 Words like "first," "next," and "finally" work okay, but if you need to add more steps in the future, for example, they can get unnecessarily unwieldy or difficult to keep track of.

janine-c · 2025-08-07T00:59:47Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+1. Select the metric you want to edit.
+1. Click **Edit** in the side panel.
+1. Apply the following updates:
+   - `k8s.pod.cpu.usage`


I'm not sure there's anything to be done about this, but it was a little jarring to see "Select the metric you want to edit" before seeing which metrics required edits. Then, at the end, it looks like you only have to click Save once, but it looks like you have to click it for each metric you're modifying.

I'm kind of toying with the idea of moving this list somewhere else - like, if it were me doing it from scratch, I might put the metrics into a table below the procedure, and then have the procedure refer down to it. But it also kind of feels like a bit of a bug workaround, and that might contribute to the kind of awkward feeling around it?

Great point. I am going to reorganize it a bit.

janine-c · 2025-08-07T01:06:08Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+  
+## Correlating traces with infrastructure metrics
+
+To correlate your APM traces with Kubernetes infrastructure metrics, Datadog uses [unified service tagging][7]. This requires setting three standard resource attributes on telemetry from both your application and your infrastructure. Datadog automatically maps these OpenTelemetry attributes to the standard Datadog tags (`env`, `service`, and `version`) used for correlation.


I clicked the unified service tagging link and it went to an OTel specific section, so I was wondering if the first instance of Datadog here should say OpenTelemetry?

Understandable confusion here. Unified Service Tagging is a Datadog feature. Datadog uses this system to correlate data by mapping standard OpenTelemetry resource attributes to standard Datadog tags (env, service, version). I have a separate PR which should make the OTel nuance more clear (which I'll swap the link to when it's ready). But it is correct to say Datadog here.

Ah, makes sense, thank you for sating my curiosity!

Thanks for your review! Great feedback!

janine-c · 2025-08-07T01:16:30Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+
+- `service.name`
+- `service.version`
+- `deployment.environment.name` (Supported in Agent v7.58.0+ and Collector Exporter v0.110.0+; otherwise, use `deployment.environment`)


I noticed that the Prerequisites section says that this guide assumes users have a newer version of the Collector Exporter. Could be worth throwing the Agent version there up too?

content/en/opentelemetry/integrations/kubernetes_metrics.md

justin-lesko · 2025-08-05T16:22:29Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+
+## Overview
+
+Collect Kubernetes metrics using the OpenTelemetry Collector to gain comprehensive insights into your cluster's health and performance. This integration uses a combination of OpenTelemetry receivers to gather data, which populates the [Containers - Overview][1] dashboard.


Can we change this (and the screenshot) to be the Kubernetes - Overview dashboard?

justin-lesko · 2025-08-05T16:28:49Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+    helm repo update
+    helm install kube-state-metrics prometheus-community/kube-state-metrics --set "metricLabelsAllowlist[0]=pods=[*]"
+    ```
+    **Note**: The `--set "metricLabelsAllowlist[0]=pods=[*]"` flag configures `kube-state-metrics` to include all available labels for pod-related metrics. This provides maximum detail but may increase cardinality in large clusters. For production environments, you may want to customize this to a specific list of required labels.


This is actually not required given the current configuration files. Pod uid is included by default in the metrics and that's all we're using the pipeline right now.

justin-lesko · 2025-08-05T16:30:05Z

content/en/opentelemetry/integrations/kubernetes_metrics.md

+
+- `service.name`
+- `service.version`
+- `deployment.environment.name` (Supported in Agent v7.58.0+ and Collector Exporter v0.110.0+; otherwise, use `deployment.environment`)


Given that these instructions are for customers who won't be using the DD agent and we've listed OTel version 0.130.0 listed as a prerequisite, I think we can delete the version notes. Perhaps we could just say "formerly deployment.environment"?

Co-authored-by: Janine Chan <[email protected]>

…blue/otel-k8s

Add new kubernetes integration page.

379222c

Cleanup.

1ab1248

github-actions bot added the Images Images are added/removed with this PR label Jul 31, 2025

brett0000FF added 2 commits July 31, 2025 09:37

Fix spacing in numbered list.

b424590

Add page to nav and index.

be4997b

github-actions bot added the Architecture Everything related to the Doc backend label Jul 31, 2025

brett0000FF requested a review from justin-lesko July 31, 2025 15:45

brett0000FF marked this pull request as ready for review July 31, 2025 15:45

brett0000FF requested a review from a team as a code owner July 31, 2025 15:45

brett0000FF added the editorial review Waiting on a more in-depth review label Jul 31, 2025

brett0000FF requested a review from shanelhuang August 4, 2025 15:27

janine-c approved these changes Aug 7, 2025

View reviewed changes

justin-lesko requested changes Aug 7, 2025

View reviewed changes

brett0000FF and others added 4 commits August 7, 2025 13:44

Apply suggestions from code review

c9ffa55

Co-authored-by: Janine Chan <[email protected]>

Merge branch 'master' of github.com:DataDog/documentation into brett.…

0fed226

…blue/otel-k8s

Apply feedback from review.

c0480d9

Fix typo and metric table.

edd8bcb

brett0000FF requested a review from justin-lesko August 7, 2025 20:15

Apply editorial review feedback.

7252194


		3. Install the OpenTelemetry Collectors

		First, add the OpenTelemetry Helm chart repository:


		## Correlating traces with infrastructure metrics

		To correlate your APM traces with Kubernetes infrastructure metrics, Datadog uses [unified service tagging][7]. This requires setting three standard resource attributes on telemetry from both your application and your infrastructure. Datadog automatically maps these OpenTelemetry attributes to the standard Datadog tags (`env`, `service`, and `version`) used for correlation.


		## Overview

		Collect Kubernetes metrics using the OpenTelemetry Collector to gain comprehensive insights into your cluster's health and performance. This integration uses a combination of OpenTelemetry receivers to gather data, which populates the [Containers - Overview][1] dashboard.

Kubernetes OTel Integration #30815

Are you sure you want to change the base?

Kubernetes OTel Integration #30815

Conversation

brett0000FF commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do? What is the motivation?

Merge instructions

Additional notes

Uh oh!

github-actions bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Documentation Team Review Required

Uh oh!

github-actions bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview links (active after the build_preview check completes)

New or renamed files

Modified Files

Uh oh!

janine-c left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

brett0000FF commented Jul 30, 2025 •

edited

Loading

github-actions bot commented Jul 30, 2025 •

edited

Loading

github-actions bot commented Jul 30, 2025 •

edited

Loading

Preview links (active after the `build_preview` check completes)