From 261f26cbf35b2833ecfe53514418e06feeaed920 Mon Sep 17 00:00:00 2001 From: Brett Blue Date: Tue, 18 Aug 2026 15:23:32 -0600 Subject: [PATCH 1/6] [DOCS-15393] Consolidate OpenTelemetry hostname recommendations Expand the Hostname and Tagging page into a canonical reference covering hostname recommendations for each OpenTelemetry ingestion path: DDOT Collector on Kubernetes, OTLP ingestion by the Datadog Agent, direct OTLP intake for serverless workloads, and the standalone Collector with the Datadog Exporter. - Add a linked summary table of recommendations by ingestion path - Split cloud resource detector lists per platform, including separate ECS on EC2 and ECS Fargate configurations - Add pointers to the canonical page from the DDOT DaemonSet, serverless, Agent OTLP ingestion, and hostname mapping pages --- .../opentelemetry/config/hostname_tagging.md | 80 +++++++++++++++---- .../en/opentelemetry/mapping/hostname.md | 6 +- .../install/kubernetes_daemonset.md | 3 + .../setup/otlp_ingest/serverless.md | 3 + .../setup/otlp_ingest_in_the_agent.md | 3 + 5 files changed, 77 insertions(+), 18 deletions(-) diff --git a/hugo/content/en/opentelemetry/config/hostname_tagging.md b/hugo/content/en/opentelemetry/config/hostname_tagging.md index 0f879615268..bc0a4d14515 100644 --- a/hugo/content/en/opentelemetry/config/hostname_tagging.md +++ b/hugo/content/en/opentelemetry/config/hostname_tagging.md @@ -1,22 +1,64 @@ --- title: Hostname and Tagging +description: Configure consistent host identification and tagging for OpenTelemetry telemetry sent to Datadog. aliases: - /opentelemetry/collector_exporter/hostname_tagging further_reading: - link: "/opentelemetry/collector_exporter/" tag: "Documentation" text: "Setting Up the OpenTelemetry Collector" +- link: "/opentelemetry/mapping/hostname/" + tag: "Documentation" + text: "Mapping OpenTelemetry Semantic Conventions to Hostnames" --- {{< img src="opentelemetry/collector_exporter/hostname_tagging.png" alt="Hostname information collected from OpenTelemetry" style="width:100%;" >}} ## Overview -To extract the correct hostname and host tags, Datadog Exporter uses the [resource detection processor][2] and the [Kubernetes attributes processor][3]. These processors allow for extracting information from hosts and containers in the form of [resource semantic conventions][1], which is then used to build the hostname, host tags, and container tags. These tags enable automatic correlation among telemetry signals and tag-based navigation for filtering and grouping telemetry data within Datadog. +Datadog uses OpenTelemetry resource attributes to associate metrics, traces, and logs with hosts. Consistent host identification enables correlation across telemetry signals and host-tag inheritance. + +The recommended configuration depends on how you send telemetry to Datadog. For the hostname resolution order and supported resource attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][8]. + +## Recommendations by ingestion path + +| Ingestion path | Recommendation | +|---|---| +| [DDOT Collector on Kubernetes](#ddot-collector-on-kubernetes) | Run DDOT as a DaemonSet and use the `infraattributes` processor. To make OTLP telemetry use the Datadog Agent hostname, enable `allow_hostname_override`. | +| [OTLP ingestion by the Datadog Agent](#otlp-ingestion-by-the-datadog-agent) | Run an Agent on every host that generates telemetry. If you set hostname attributes, match them to the Agent hostname; otherwise, omit them to use the Agent hostname as the fallback. | +| [Direct OTLP intake for serverless workloads](#direct-otlp-intake-for-serverless-workloads) | Use platform-specific resource attributes for workload identification. Direct OTLP intake does not populate the Infrastructure List. | +| [Standalone Collector with the Datadog Exporter](#standalone-collector-with-the-datadog-exporter) | Run a Collector on each host and use the `resourcedetection` processor. For agent-to-gateway deployments, detect host information in the agent Collector and preserve the resource attributes through the gateway. | + +### DDOT Collector on Kubernetes + +The DDOT Collector's `infraattributes` processor adds infrastructure attributes and tags to OTLP telemetry. Include it in every signal pipeline, as shown in the [DDOT Collector DaemonSet setup][9]. + +When DDOT and the Datadog Agent monitor the same node, use the Agent hostname for OTLP telemetry to prevent the node from appearing under multiple names: + +```yaml +processors: + infraattributes: + cardinality: 2 + allow_hostname_override: true +``` + +The processor needs resource attributes that identify the source container. If infrastructure tags are missing, see [Infrastructure tags are missing from telemetry][10]. + +### OTLP ingestion by the Datadog Agent + +Deploy the Datadog Agent on every host that generates OTLP telemetry. Sending telemetry from one host to an Agent on another host is not supported. + +If incoming telemetry has no valid hostname attributes, Datadog uses the Agent hostname. If you set `host.name`, `host.id`, or another hostname attribute explicitly, make its value consistent with the Agent hostname to avoid duplicate hosts. See [OTLP Ingestion by the Datadog Agent][11] for setup instructions. -For more information, see the OpenTelemetry project documentation for the [resource detection][2] and [Kubernetes attributes][3] processors. +### Direct OTLP intake for serverless workloads -## Setup +For serverless and managed platforms, set the cloud and platform resource attributes for your environment instead of relying on `host.name` for workload identification. See [OTLP Intake for Serverless][12] for the required attributes. + +Host metadata sent through [direct OTLP intake][14] does not populate the [Infrastructure List][13]. + +### Standalone Collector with the Datadog Exporter + +The Datadog Exporter uses the [resource detection processor][2] and the [Kubernetes attributes processor][3] to collect host and container resource attributes. Add the appropriate processors to the relevant metrics, traces, and logs pipelines. {{< tabs >}} {{% tab "Host" %}} @@ -26,7 +68,7 @@ Add the following lines to your Collector configuration: ```yaml processors: resourcedetection: - # bare metal + # Bare metal detectors: [env, system] system: resource_attributes: @@ -46,16 +88,18 @@ processors: enabled: true host.cpu.cache.l2.size: enabled: true - # GCP - detectors: [env, gcp, system] - # AWS - detectors: [env, ecs, ec2, system] - # Azure - detectors: [env, azure, system] timeout: 2s override: false ``` +For cloud environments, replace `detectors` with the appropriate list: + +- Amazon EC2: `[env, ec2, system]` +- Amazon ECS on EC2: `[env, ecs, ec2, system]` +- Amazon ECS Fargate: `[env, ecs]` +- Google Cloud: `[env, gcp, system]` +- Azure: `[env, azure, system]` + {{% /tab %}} {{% tab "Kubernetes Daemonset" %}} @@ -292,7 +336,7 @@ processors: {{% /tab %}} {{< /tabs >}} -## Data collected +#### Data collected | OpenTelemetry attribute | Datadog Tag | Processor | |---|---|---| @@ -352,11 +396,11 @@ processors: | `container.image.tag` | `image_tag` | `k8sattributes` | -## Full example configuration +#### Full example configuration For a full working example configuration with the Datadog exporter, see [`k8s-values.yaml`][4]. This example is for Amazon EKS. -## Example logging output +#### Example logging output ``` ResourceSpans #0 @@ -493,10 +537,16 @@ processors: from_attribute: ``` -[1]: https://opentelemetry.io/docs/specs/semconv/resource/ [2]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md [3]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/k8sattributesprocessor/README.md [4]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/datadogexporter/examples/k8s-chart/k8s-values.yaml [5]: https://opentelemetry.io/docs/languages/js/resources/ [6]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/datadogexporter/examples/collector.yaml -[7]: https://docs.datadoghq.com/opentelemetry/schema_semantics/host_metadata/ +[7]: /opentelemetry/mapping/host_metadata/ +[8]: /opentelemetry/mapping/hostname/ +[9]: /opentelemetry/setup/ddot_collector/install/kubernetes_daemonset/ +[10]: /opentelemetry/troubleshooting/#infrastructure-tags-are-missing-from-telemetry +[11]: /opentelemetry/setup/otlp_ingest_in_the_agent/ +[12]: /opentelemetry/setup/otlp_ingest/serverless/ +[13]: /infrastructure/list/ +[14]: /opentelemetry/setup/otlp_ingest/ diff --git a/hugo/content/en/opentelemetry/mapping/hostname.md b/hugo/content/en/opentelemetry/mapping/hostname.md index a519bc5abf1..675301abbe8 100644 --- a/hugo/content/en/opentelemetry/mapping/hostname.md +++ b/hugo/content/en/opentelemetry/mapping/hostname.md @@ -12,7 +12,7 @@ further_reading: OpenTelemetry defines certain semantic conventions for resource attributes related to hostnames. If an OpenTelemetry Protocol (OTLP) payload for any signal type has known hostname resource attributes, Datadog honors these conventions and tries to use its value as a hostname. The default hostname resolution algorithm is built with compatibility with the rest of Datadog products in mind, but you can override it if needed. -This algorithm is used in the [Datadog exporter][3] as well as the [OTLP ingest pipeline in the Datadog Agent][2] and [DDOT Collector][5]. When using the [recommended configuration][4] for the Datadog exporter, the [resource detection processor][1] adds the necessary resource attributes to the payload to ensure accurate hostname resolution. +This algorithm is used in the [Datadog exporter][3] as well as the [OTLP ingest pipeline in the Datadog Agent][2] and [DDOT Collector][5]. When using the [configuration recommendations for your ingestion path][4], the [resource detection processor][1] adds the necessary resource attributes to the payload for accurate hostname resolution. ## Conventions used to determine the hostname @@ -146,7 +146,7 @@ The following host names are deemed invalid and discarded: [1]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#resource-detection-processor [2]: /opentelemetry/interoperability/otlp_ingest_in_the_agent [3]: /opentelemetry/setup/collector_exporter/ -[4]: /opentelemetry/config/hostname_tagging/ +[4]: /opentelemetry/config/hostname_tagging/#recommendations-by-ingestion-path [5]: /opentelemetry/migrate/ddot_collector/ [6]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor -[7]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor#expected-attributes \ No newline at end of file +[7]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor#expected-attributes diff --git a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md index a0b087050b5..a00485dc05c 100644 --- a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md +++ b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md @@ -694,6 +694,8 @@ service: {{% /tab %}} {{< /tabs >}} +The `infraattributes` processor can also apply the Agent hostname to OTLP telemetry. See [Hostname and Tagging][58] for hostname recommendations and the Agent hostname override. + #### Key components To send telemetry data to Datadog, the following components are defined in the configuration: @@ -974,3 +976,4 @@ View metrics from the DDOT Collector to monitor the Collector health. [55]: /containers/datadog_operator [56]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ [57]: https://github.com/DataDog/helm-charts/blob/main/charts/datadog-operator/README.md +[58]: /opentelemetry/config/hostname_tagging/#ddot-collector-on-kubernetes diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md index 466fbcefcee..950f1be232e 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md @@ -40,6 +40,8 @@ The following configuration applies to all platforms. **Resource attributes**: Set platform-specific attributes with `OTEL_RESOURCE_ATTRIBUTES`. See each cloud provider tab below for required and optional attributes. +Use the platform attributes on this page for workload identification instead of relying on `host.name`. For recommendations across other ingestion paths, see [Hostname and Tagging][6]. + ```shell export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf" export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="{{< region-param key="otlp_trace_endpoint" >}}" @@ -212,3 +214,4 @@ The GCP Resource Detector SDK automatically populates: `cloud.account.id`, `clou [3]: /opentelemetry/setup/otlp_ingest/logs/ [4]: /opentelemetry/setup/otlp_ingest/metrics/ [5]: /opentelemetry/setup/otlp_ingest/managed_platforms/ +[6]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-for-serverless-workloads diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md index 91cb86462e9..6cd85855743 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md @@ -35,6 +35,8 @@ Read the OpenTelemetry instrumentation documentation to understand how to point
The supported setup is an ingesting Agent deployed on every OpenTelemetry-data generating host. You cannot send OpenTelemetry telemetry from collectors or instrumented apps running one host to an Agent on a different host. But, provided the Agent is local to the collector or SDK instrumented app, you can set up multiple pipelines.
+For hostname recommendations across OpenTelemetry ingestion paths, see [Hostname and Tagging][11]. + ## Enabling OTLP Ingestion on the Datadog Agent {{< tabs >}} @@ -392,3 +394,4 @@ env: [5]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/receiver/otlpreceiver/config.md [6]: /agent/configuration/agent-configuration-files/ [10]: /opentelemetry/runtime_metrics/ +[11]: /opentelemetry/config/hostname_tagging/#otlp-ingestion-by-the-datadog-agent From a453825c05c86812b75404a82d3db5d831b3864b Mon Sep 17 00:00:00 2001 From: Brett Blue Date: Tue, 18 Aug 2026 17:44:53 -0600 Subject: [PATCH 2/6] Group hostname recommendations by deployment topology Reorganize the recommendations around where telemetry is collected relative to the workload, rather than by installation page: - Agent or DDOT Collector co-located with the workload - Node-level Collector sending to a gateway - Collector on each host with the Datadog Exporter - Direct OTLP intake without a host Also: - Correct the DDOT hostname explanation. DDOT runs inside the Datadog Agent, so the duplicate-host case is conflicting hostname attributes on incoming telemetry, not co-location. - Document datadog.host.name as the explicit override. - Name Fargate, gateway, and managed platform workflows. Fargate spans two topologies, so each section points to the other. - Drop the unrelated cardinality setting from the override example. - Restore h3 on the exporter reference headings so they appear in the table of contents, and split that reference material into its own section. - Use "Infrastructure Host List" and keep the danger callout. - Add reciprocal links from troubleshooting, the DDOT gateway page, and managed platforms. --- .../opentelemetry/config/hostname_tagging.md | 73 +++++++++++++------ .../en/opentelemetry/mapping/hostname.md | 2 +- .../install/kubernetes_daemonset.md | 4 +- .../install/kubernetes_gateway.md | 3 + .../setup/otlp_ingest/managed_platforms.md | 3 + .../setup/otlp_ingest/serverless.md | 4 +- .../setup/otlp_ingest_in_the_agent.md | 4 +- .../en/opentelemetry/troubleshooting.md | 3 +- 8 files changed, 64 insertions(+), 32 deletions(-) diff --git a/hugo/content/en/opentelemetry/config/hostname_tagging.md b/hugo/content/en/opentelemetry/config/hostname_tagging.md index bc0a4d14515..0638d33235c 100644 --- a/hugo/content/en/opentelemetry/config/hostname_tagging.md +++ b/hugo/content/en/opentelemetry/config/hostname_tagging.md @@ -18,45 +18,64 @@ further_reading: Datadog uses OpenTelemetry resource attributes to associate metrics, traces, and logs with hosts. Consistent host identification enables correlation across telemetry signals and host-tag inheritance. -The recommended configuration depends on how you send telemetry to Datadog. For the hostname resolution order and supported resource attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][8]. +The recommended configuration depends on where your telemetry is collected relative to your workload. For the hostname resolution order and the full list of supported resource attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][8]. -## Recommendations by ingestion path +## Recommendations by topology -| Ingestion path | Recommendation | +Find your deployment topology in the following table, then follow the linked section. Topology matters more than which product you install. + +| Topology | Recommendation | |---|---| -| [DDOT Collector on Kubernetes](#ddot-collector-on-kubernetes) | Run DDOT as a DaemonSet and use the `infraattributes` processor. To make OTLP telemetry use the Datadog Agent hostname, enable `allow_hostname_override`. | -| [OTLP ingestion by the Datadog Agent](#otlp-ingestion-by-the-datadog-agent) | Run an Agent on every host that generates telemetry. If you set hostname attributes, match them to the Agent hostname; otherwise, omit them to use the Agent hostname as the fallback. | -| [Direct OTLP intake for serverless workloads](#direct-otlp-intake-for-serverless-workloads) | Use platform-specific resource attributes for workload identification. Direct OTLP intake does not populate the Infrastructure List. | -| [Standalone Collector with the Datadog Exporter](#standalone-collector-with-the-datadog-exporter) | Run a Collector on each host and use the `resourcedetection` processor. For agent-to-gateway deployments, detect host information in the agent Collector and preserve the resource attributes through the gateway. | +| [Agent or DDOT Collector on the same host as your workload](#agent-or-ddot-collector-on-the-same-host-as-your-workload) | The Datadog Agent hostname is authoritative. Omit hostname attributes, or set them to match the Agent hostname. | +| [Node-level Collector sending to a gateway](#node-level-collector-sending-to-a-gateway) | Detect host information in the node-level Collector and preserve those resource attributes through the gateway. | +| [Collector on each host with the Datadog Exporter](#collector-on-each-host-with-the-datadog-exporter) | Use the `resourcedetection` processor with the detectors for your environment. | +| [Direct OTLP intake without a host](#direct-otlp-intake-without-a-host) | Set platform resource attributes instead of `host.name`. | + +### Agent or DDOT Collector on the same host as your workload + +This topology covers [OTLP ingestion by the Datadog Agent][11], the [DDOT Collector as a DaemonSet][9], the DDOT Collector on [Linux][14] and [Windows][15] hosts, and the DDOT Collector sidecar on [ECS Fargate][16] and [EKS Fargate][17]. -### DDOT Collector on Kubernetes +Deploy the Agent or DDOT Collector on every host that generates OTLP telemetry. Sending telemetry from one host to an Agent on another host is not supported. -The DDOT Collector's `infraattributes` processor adds infrastructure attributes and tags to OTLP telemetry. Include it in every signal pipeline, as shown in the [DDOT Collector DaemonSet setup][9]. +If incoming telemetry has no valid hostname attributes, Datadog uses the Agent hostname. If you set `host.name`, `host.id`, or another hostname attribute, make its value match the Agent hostname to avoid duplicate hosts. When you do not control the attributes that your applications emit, set the `datadog.host.name` resource attribute to override hostname resolution explicitly. -When DDOT and the Datadog Agent monitor the same node, use the Agent hostname for OTLP telemetry to prevent the node from appearing under multiple names: +The DDOT Collector's `infraattributes` processor adds infrastructure attributes and tags to OTLP telemetry. Include it in every signal pipeline. Because the DDOT Collector runs inside the Datadog Agent, hostname attributes on incoming telemetry can resolve to a different name than the Agent's, which makes a single node appear as two hosts. Enable `allow_hostname_override` to use the Agent hostname instead: ```yaml processors: infraattributes: - cardinality: 2 allow_hostname_override: true ``` -The processor needs resource attributes that identify the source container. If infrastructure tags are missing, see [Infrastructure tags are missing from telemetry][10]. +On ECS Fargate and EKS Fargate, add the `resourcedetection` processor alongside `infraattributes` and set the detectors for your platform: `[env, ecs]` for ECS Fargate, or `[env, eks]` for EKS Fargate. + +The `infraattributes` processor needs resource attributes that identify the source container. If infrastructure tags are missing, see [Infrastructure tags are missing from telemetry][10]. + +### Node-level Collector sending to a gateway + +This topology covers gateway deployments of the OpenTelemetry Collector with the Datadog Exporter, and the [DDOT Collector as a gateway on Kubernetes][18]. + +In a gateway deployment, the Collector that exports to Datadog does not run on the host that produced the telemetry. If host information is not attached before the data reaches the gateway, telemetry from many hosts can collapse onto the gateway's hostname, or each Collector pod can register as its own host. + +Detect host information in the node-level Collector, then configure the gateway to preserve those resource attributes instead of detecting them again. For the Datadog Exporter, use the **Kubernetes DaemonSet -> Gateway** configuration in [Datadog Exporter configuration](#datadog-exporter-configuration). If a gateway deployment reports the wrong host, see [Gateway collector not forwarding host metadata][19]. + +### Collector on each host with the Datadog Exporter + +This topology covers the [OpenTelemetry Collector with the Datadog Exporter][20] running on each host or as a Kubernetes DaemonSet. -### OTLP ingestion by the Datadog Agent +Run a Collector on every host and add the `resourcedetection` processor with the detectors for your environment, as described in [Datadog Exporter configuration](#datadog-exporter-configuration). -Deploy the Datadog Agent on every host that generates OTLP telemetry. Sending telemetry from one host to an Agent on another host is not supported. +### Direct OTLP intake without a host -If incoming telemetry has no valid hostname attributes, Datadog uses the Agent hostname. If you set `host.name`, `host.id`, or another hostname attribute explicitly, make its value consistent with the Agent hostname to avoid duplicate hosts. See [OTLP Ingestion by the Datadog Agent][11] for setup instructions. +This topology covers [OTLP intake for serverless platforms][12], such as AWS Lambda, ECS Fargate, Azure Functions, and Cloud Run, and [OTLP intake for managed platforms][13]. -### Direct OTLP intake for serverless workloads +These workloads have no host to identify. Set the cloud and platform resource attributes for your environment instead of relying on `host.name` for workload identification. Each platform requires a different set of attributes. -For serverless and managed platforms, set the cloud and platform resource attributes for your environment instead of relying on `host.name` for workload identification. See [OTLP Intake for Serverless][12] for the required attributes. +
Host metadata sent to the OTLP intake endpoints does not populate the Infrastructure Host List.
-Host metadata sent through [direct OTLP intake][14] does not populate the [Infrastructure List][13]. +If you run the DDOT Collector as a sidecar on ECS Fargate or EKS Fargate rather than sending to an OTLP intake endpoint, follow [Agent or DDOT Collector on the same host as your workload](#agent-or-ddot-collector-on-the-same-host-as-your-workload). -### Standalone Collector with the Datadog Exporter +## Datadog Exporter configuration The Datadog Exporter uses the [resource detection processor][2] and the [Kubernetes attributes processor][3] to collect host and container resource attributes. Add the appropriate processors to the relevant metrics, traces, and logs pipelines. @@ -336,7 +355,7 @@ processors: {{% /tab %}} {{< /tabs >}} -#### Data collected +### Data collected | OpenTelemetry attribute | Datadog Tag | Processor | |---|---|---| @@ -396,11 +415,11 @@ processors: | `container.image.tag` | `image_tag` | `k8sattributes` | -#### Full example configuration +### Full example configuration For a full working example configuration with the Datadog exporter, see [`k8s-values.yaml`][4]. This example is for Amazon EKS. -#### Example logging output +### Example logging output ``` ResourceSpans #0 @@ -548,5 +567,11 @@ processors: [10]: /opentelemetry/troubleshooting/#infrastructure-tags-are-missing-from-telemetry [11]: /opentelemetry/setup/otlp_ingest_in_the_agent/ [12]: /opentelemetry/setup/otlp_ingest/serverless/ -[13]: /infrastructure/list/ -[14]: /opentelemetry/setup/otlp_ingest/ +[13]: /opentelemetry/setup/otlp_ingest/managed_platforms/ +[14]: /opentelemetry/setup/ddot_collector/install/linux/ +[15]: /opentelemetry/setup/ddot_collector/install/windows/ +[16]: /opentelemetry/setup/ddot_collector/install/ecs_fargate/ +[17]: /opentelemetry/setup/ddot_collector/install/eks_fargate/ +[18]: /opentelemetry/setup/ddot_collector/install/kubernetes_gateway/ +[19]: /opentelemetry/troubleshooting/#gateway-collector-not-forwarding-host-metadata +[20]: /opentelemetry/setup/collector_exporter/ diff --git a/hugo/content/en/opentelemetry/mapping/hostname.md b/hugo/content/en/opentelemetry/mapping/hostname.md index 675301abbe8..56f9305ae56 100644 --- a/hugo/content/en/opentelemetry/mapping/hostname.md +++ b/hugo/content/en/opentelemetry/mapping/hostname.md @@ -146,7 +146,7 @@ The following host names are deemed invalid and discarded: [1]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#resource-detection-processor [2]: /opentelemetry/interoperability/otlp_ingest_in_the_agent [3]: /opentelemetry/setup/collector_exporter/ -[4]: /opentelemetry/config/hostname_tagging/#recommendations-by-ingestion-path +[4]: /opentelemetry/config/hostname_tagging/#recommendations-by-topology [5]: /opentelemetry/migrate/ddot_collector/ [6]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor [7]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor#expected-attributes diff --git a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md index a00485dc05c..f4a93427ea5 100644 --- a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md +++ b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md @@ -694,7 +694,7 @@ service: {{% /tab %}} {{< /tabs >}} -The `infraattributes` processor can also apply the Agent hostname to OTLP telemetry. See [Hostname and Tagging][58] for hostname recommendations and the Agent hostname override. +Because the DDOT Collector runs inside the Datadog Agent, hostname attributes on incoming telemetry can resolve to a different name than the Agent's. The `infraattributes` processor can apply the Agent hostname instead. See [Hostname and Tagging][58] for the recommended configuration. #### Key components @@ -976,4 +976,4 @@ View metrics from the DDOT Collector to monitor the Collector health. [55]: /containers/datadog_operator [56]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ [57]: https://github.com/DataDog/helm-charts/blob/main/charts/datadog-operator/README.md -[58]: /opentelemetry/config/hostname_tagging/#ddot-collector-on-kubernetes +[58]: /opentelemetry/config/hostname_tagging/#agent-or-ddot-collector-on-the-same-host-as-your-workload diff --git a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md index 889d0fb7014..58b23628584 100644 --- a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md +++ b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md @@ -484,6 +484,8 @@ If you set fullnameOverride, the gateway's Kubernetes service name The example configurations use insecure TLS for simplicity. Follow the [OTel configtls instructions][7] if you want to enable TLS. +In a gateway deployment, host information must be attached before telemetry reaches the gateway. For the recommended hostname configuration, see [Hostname and Tagging][12]. + ### Advanced configuration options {{< tabs >}} @@ -1371,3 +1373,4 @@ To view your gateway pods: [9]: http://github.com/kubernetes-sigs/metrics-server [10]: /containers/guide/cluster_agent_autoscaling_metrics/?tab=helm [11]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/datadogextension +[12]: /opentelemetry/config/hostname_tagging/#node-level-collector-sending-to-a-gateway diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md b/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md index 50e601be9f6..2c9d787baed 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md @@ -20,6 +20,8 @@ Use this option when you run workloads on a managed platform where installing a
Host metadata sent to managed platform endpoints does not populate the Infrastructure Host List.
+For hostname recommendations across OpenTelemetry deployment topologies, see [Hostname and Tagging][18]. + Each endpoint supports the following signal paths: | Signal | Path | @@ -120,3 +122,4 @@ Sampling controls available in the Collector (tail-based sampling, probabilistic [15]: https://docs.mulesoft.com/monitoring/telemetry-exporter [16]: https://docs.retool.com/apps/guides/observability/performance-monitoring [17]: https://vercel.com/marketplace/datadog +[18]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-without-a-host diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md index 950f1be232e..fa27950a4c3 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md @@ -40,7 +40,7 @@ The following configuration applies to all platforms. **Resource attributes**: Set platform-specific attributes with `OTEL_RESOURCE_ATTRIBUTES`. See each cloud provider tab below for required and optional attributes. -Use the platform attributes on this page for workload identification instead of relying on `host.name`. For recommendations across other ingestion paths, see [Hostname and Tagging][6]. +Use the platform attributes on this page for workload identification instead of relying on `host.name`. For hostname recommendations across OpenTelemetry deployment topologies, see [Hostname and Tagging][6]. ```shell export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf" @@ -214,4 +214,4 @@ The GCP Resource Detector SDK automatically populates: `cloud.account.id`, `clou [3]: /opentelemetry/setup/otlp_ingest/logs/ [4]: /opentelemetry/setup/otlp_ingest/metrics/ [5]: /opentelemetry/setup/otlp_ingest/managed_platforms/ -[6]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-for-serverless-workloads +[6]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-without-a-host diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md index 6cd85855743..5c3cc5d210d 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md @@ -35,7 +35,7 @@ Read the OpenTelemetry instrumentation documentation to understand how to point
The supported setup is an ingesting Agent deployed on every OpenTelemetry-data generating host. You cannot send OpenTelemetry telemetry from collectors or instrumented apps running one host to an Agent on a different host. But, provided the Agent is local to the collector or SDK instrumented app, you can set up multiple pipelines.
-For hostname recommendations across OpenTelemetry ingestion paths, see [Hostname and Tagging][11]. +For hostname recommendations across OpenTelemetry deployment topologies, see [Hostname and Tagging][11]. ## Enabling OTLP Ingestion on the Datadog Agent @@ -394,4 +394,4 @@ env: [5]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/receiver/otlpreceiver/config.md [6]: /agent/configuration/agent-configuration-files/ [10]: /opentelemetry/runtime_metrics/ -[11]: /opentelemetry/config/hostname_tagging/#otlp-ingestion-by-the-datadog-agent +[11]: /opentelemetry/config/hostname_tagging/#agent-or-ddot-collector-on-the-same-host-as-your-workload diff --git a/hugo/content/en/opentelemetry/troubleshooting.md b/hugo/content/en/opentelemetry/troubleshooting.md index 66d49701fce..7d9ef466b48 100644 --- a/hugo/content/en/opentelemetry/troubleshooting.md +++ b/hugo/content/en/opentelemetry/troubleshooting.md @@ -53,7 +53,7 @@ Alternatively, you can override the hostname using the `datadog.host.name` attri - set(attributes["datadog.host.name"], "${NODE_NAME}") ``` -For more information on host-identifying attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][2]. +For more information on host-identifying attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][2]. For the recommended configuration in each deployment topology, see [Hostname and Tagging][9]. ### Unexpected hostnames with AWS Fargate deployment @@ -349,3 +349,4 @@ features: [6]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#readme [7]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor#readme [8]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainerID +[9]: /opentelemetry/config/hostname_tagging/#recommendations-by-topology From 76db3c9934ef71249dfd7fd02d7b1db851fe6559 Mon Sep 17 00:00:00 2001 From: Brett Blue Date: Tue, 18 Aug 2026 17:54:48 -0600 Subject: [PATCH 3/6] Replace "topology" with plain wording "Topology" was not established vocabulary in these docs, and it needed a justifying sentence to earn its place. The four section titles already distinguish the cases, so the grouping does not need naming. Avoided "deployment pattern" as the replacement: the DDOT install pages already use it for the narrower Agent-vs-Gateway distinction, which cuts across this four-way split. Section anchor is now #hostname-recommendations; inbound links updated. --- .../en/opentelemetry/config/hostname_tagging.md | 14 +++++++------- hugo/content/en/opentelemetry/mapping/hostname.md | 2 +- .../setup/otlp_ingest/managed_platforms.md | 2 +- .../opentelemetry/setup/otlp_ingest/serverless.md | 2 +- .../setup/otlp_ingest_in_the_agent.md | 2 +- hugo/content/en/opentelemetry/troubleshooting.md | 4 ++-- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/hugo/content/en/opentelemetry/config/hostname_tagging.md b/hugo/content/en/opentelemetry/config/hostname_tagging.md index 0638d33235c..b04a7048589 100644 --- a/hugo/content/en/opentelemetry/config/hostname_tagging.md +++ b/hugo/content/en/opentelemetry/config/hostname_tagging.md @@ -20,11 +20,11 @@ Datadog uses OpenTelemetry resource attributes to associate metrics, traces, and The recommended configuration depends on where your telemetry is collected relative to your workload. For the hostname resolution order and the full list of supported resource attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][8]. -## Recommendations by topology +## Hostname recommendations -Find your deployment topology in the following table, then follow the linked section. Topology matters more than which product you install. +The right configuration depends on where telemetry is collected relative to the workload that produced it. Find your setup in the following table, then follow the linked section. -| Topology | Recommendation | +| How you collect telemetry | Recommendation | |---|---| | [Agent or DDOT Collector on the same host as your workload](#agent-or-ddot-collector-on-the-same-host-as-your-workload) | The Datadog Agent hostname is authoritative. Omit hostname attributes, or set them to match the Agent hostname. | | [Node-level Collector sending to a gateway](#node-level-collector-sending-to-a-gateway) | Detect host information in the node-level Collector and preserve those resource attributes through the gateway. | @@ -33,7 +33,7 @@ Find your deployment topology in the following table, then follow the linked sec ### Agent or DDOT Collector on the same host as your workload -This topology covers [OTLP ingestion by the Datadog Agent][11], the [DDOT Collector as a DaemonSet][9], the DDOT Collector on [Linux][14] and [Windows][15] hosts, and the DDOT Collector sidecar on [ECS Fargate][16] and [EKS Fargate][17]. +This applies to [OTLP ingestion by the Datadog Agent][11], the [DDOT Collector as a DaemonSet][9], the DDOT Collector on [Linux][14] and [Windows][15] hosts, and the DDOT Collector sidecar on [ECS Fargate][16] and [EKS Fargate][17]. Deploy the Agent or DDOT Collector on every host that generates OTLP telemetry. Sending telemetry from one host to an Agent on another host is not supported. @@ -53,7 +53,7 @@ The `infraattributes` processor needs resource attributes that identify the sour ### Node-level Collector sending to a gateway -This topology covers gateway deployments of the OpenTelemetry Collector with the Datadog Exporter, and the [DDOT Collector as a gateway on Kubernetes][18]. +This applies to gateway deployments of the OpenTelemetry Collector with the Datadog Exporter, and the [DDOT Collector as a gateway on Kubernetes][18]. In a gateway deployment, the Collector that exports to Datadog does not run on the host that produced the telemetry. If host information is not attached before the data reaches the gateway, telemetry from many hosts can collapse onto the gateway's hostname, or each Collector pod can register as its own host. @@ -61,13 +61,13 @@ Detect host information in the node-level Collector, then configure the gateway ### Collector on each host with the Datadog Exporter -This topology covers the [OpenTelemetry Collector with the Datadog Exporter][20] running on each host or as a Kubernetes DaemonSet. +This applies to the [OpenTelemetry Collector with the Datadog Exporter][20] running on each host or as a Kubernetes DaemonSet. Run a Collector on every host and add the `resourcedetection` processor with the detectors for your environment, as described in [Datadog Exporter configuration](#datadog-exporter-configuration). ### Direct OTLP intake without a host -This topology covers [OTLP intake for serverless platforms][12], such as AWS Lambda, ECS Fargate, Azure Functions, and Cloud Run, and [OTLP intake for managed platforms][13]. +This applies to [OTLP intake for serverless platforms][12], such as AWS Lambda, ECS Fargate, Azure Functions, and Cloud Run, and [OTLP intake for managed platforms][13]. These workloads have no host to identify. Set the cloud and platform resource attributes for your environment instead of relying on `host.name` for workload identification. Each platform requires a different set of attributes. diff --git a/hugo/content/en/opentelemetry/mapping/hostname.md b/hugo/content/en/opentelemetry/mapping/hostname.md index 56f9305ae56..39bdacdbba2 100644 --- a/hugo/content/en/opentelemetry/mapping/hostname.md +++ b/hugo/content/en/opentelemetry/mapping/hostname.md @@ -146,7 +146,7 @@ The following host names are deemed invalid and discarded: [1]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#resource-detection-processor [2]: /opentelemetry/interoperability/otlp_ingest_in_the_agent [3]: /opentelemetry/setup/collector_exporter/ -[4]: /opentelemetry/config/hostname_tagging/#recommendations-by-topology +[4]: /opentelemetry/config/hostname_tagging/#hostname-recommendations [5]: /opentelemetry/migrate/ddot_collector/ [6]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor [7]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor#expected-attributes diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md b/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md index 2c9d787baed..9b8c50fb2e7 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md @@ -20,7 +20,7 @@ Use this option when you run workloads on a managed platform where installing a
Host metadata sent to managed platform endpoints does not populate the Infrastructure Host List.
-For hostname recommendations across OpenTelemetry deployment topologies, see [Hostname and Tagging][18]. +For hostname recommendations across OpenTelemetry setups, see [Hostname and Tagging][18]. Each endpoint supports the following signal paths: diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md index fa27950a4c3..b469caf0479 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md @@ -40,7 +40,7 @@ The following configuration applies to all platforms. **Resource attributes**: Set platform-specific attributes with `OTEL_RESOURCE_ATTRIBUTES`. See each cloud provider tab below for required and optional attributes. -Use the platform attributes on this page for workload identification instead of relying on `host.name`. For hostname recommendations across OpenTelemetry deployment topologies, see [Hostname and Tagging][6]. +Use the platform attributes on this page for workload identification instead of relying on `host.name`. For hostname recommendations across OpenTelemetry setups, see [Hostname and Tagging][6]. ```shell export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf" diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md index 5c3cc5d210d..958d16a5065 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md @@ -35,7 +35,7 @@ Read the OpenTelemetry instrumentation documentation to understand how to point
The supported setup is an ingesting Agent deployed on every OpenTelemetry-data generating host. You cannot send OpenTelemetry telemetry from collectors or instrumented apps running one host to an Agent on a different host. But, provided the Agent is local to the collector or SDK instrumented app, you can set up multiple pipelines.
-For hostname recommendations across OpenTelemetry deployment topologies, see [Hostname and Tagging][11]. +For hostname recommendations across OpenTelemetry setups, see [Hostname and Tagging][11]. ## Enabling OTLP Ingestion on the Datadog Agent diff --git a/hugo/content/en/opentelemetry/troubleshooting.md b/hugo/content/en/opentelemetry/troubleshooting.md index 7d9ef466b48..de3d3aabcb5 100644 --- a/hugo/content/en/opentelemetry/troubleshooting.md +++ b/hugo/content/en/opentelemetry/troubleshooting.md @@ -53,7 +53,7 @@ Alternatively, you can override the hostname using the `datadog.host.name` attri - set(attributes["datadog.host.name"], "${NODE_NAME}") ``` -For more information on host-identifying attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][2]. For the recommended configuration in each deployment topology, see [Hostname and Tagging][9]. +For more information on host-identifying attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][2]. For the recommended hostname configuration for your setup, see [Hostname and Tagging][9]. ### Unexpected hostnames with AWS Fargate deployment @@ -349,4 +349,4 @@ features: [6]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#readme [7]: https://github.com/DataDog/datadog-agent/tree/main/comp/otelcol/otlp/components/processor/infraattributesprocessor#readme [8]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource#WithContainerID -[9]: /opentelemetry/config/hostname_tagging/#recommendations-by-topology +[9]: /opentelemetry/config/hostname_tagging/#hostname-recommendations From 4a537b2f538a468509d59ecb571cb064e9f909a6 Mon Sep 17 00:00:00 2001 From: Brett Blue Date: Tue, 18 Aug 2026 18:03:31 -0600 Subject: [PATCH 4/6] Split hostname recommendations into five exclusive paths The four groups overlapped: a Collector DaemonSet forwarding to a gateway matched two of them, and the Agent and DDOT Collector were combined even though they call for different actions. Split into five paths a reader can self-select from: Agent OTLP ingestion, DDOT exporting directly, any Collector exporting through a gateway, the OpenTelemetry Collector with the Datadog Exporter, and direct OTLP intake. Also: - Scope the host-based guidance so it no longer covers Fargate. ECS Fargate does not support host-based deployments, so the Agent runs as a sidecar and the Agent hostname advice does not apply there. - Correct the ECS Fargate attribute source: infraattributes needs aws.ecs.task.arn from the SDK's ECS detector, not a Collector-side [env, ecs] resourcedetection processor. - Remove the duplicated statement of the organizing axis from Overview. - Use "host tag inheritance" to match the rest of the docs. --- .../opentelemetry/config/hostname_tagging.md | 58 ++++++++++++------- .../install/kubernetes_daemonset.md | 2 +- .../install/kubernetes_gateway.md | 2 +- .../setup/otlp_ingest/managed_platforms.md | 2 +- .../setup/otlp_ingest/serverless.md | 2 +- .../setup/otlp_ingest_in_the_agent.md | 2 +- 6 files changed, 41 insertions(+), 27 deletions(-) diff --git a/hugo/content/en/opentelemetry/config/hostname_tagging.md b/hugo/content/en/opentelemetry/config/hostname_tagging.md index b04a7048589..b66a8c7bae8 100644 --- a/hugo/content/en/opentelemetry/config/hostname_tagging.md +++ b/hugo/content/en/opentelemetry/config/hostname_tagging.md @@ -16,30 +16,39 @@ further_reading: ## Overview -Datadog uses OpenTelemetry resource attributes to associate metrics, traces, and logs with hosts. Consistent host identification enables correlation across telemetry signals and host-tag inheritance. +Datadog uses OpenTelemetry resource attributes to associate metrics, traces, and logs with hosts. Consistent host identification enables correlation across telemetry signals and host tag inheritance. -The recommended configuration depends on where your telemetry is collected relative to your workload. For the hostname resolution order and the full list of supported resource attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][8]. +For the hostname resolution order and the full list of supported resource attributes, see [Mapping OpenTelemetry Semantic Conventions to Hostnames][8]. ## Hostname recommendations -The right configuration depends on where telemetry is collected relative to the workload that produced it. Find your setup in the following table, then follow the linked section. +The right configuration depends on how you send telemetry to Datadog. Find your setup in the following table, then follow the linked section. -| How you collect telemetry | Recommendation | +| How you send telemetry | Recommendation | |---|---| -| [Agent or DDOT Collector on the same host as your workload](#agent-or-ddot-collector-on-the-same-host-as-your-workload) | The Datadog Agent hostname is authoritative. Omit hostname attributes, or set them to match the Agent hostname. | -| [Node-level Collector sending to a gateway](#node-level-collector-sending-to-a-gateway) | Detect host information in the node-level Collector and preserve those resource attributes through the gateway. | -| [Collector on each host with the Datadog Exporter](#collector-on-each-host-with-the-datadog-exporter) | Use the `resourcedetection` processor with the detectors for your environment. | -| [Direct OTLP intake without a host](#direct-otlp-intake-without-a-host) | Set platform resource attributes instead of `host.name`. | +| [OTLP ingestion by the Datadog Agent](#otlp-ingestion-by-the-datadog-agent) | Run an Agent on every host that generates telemetry. Omit hostname attributes, or set them to match the Agent hostname. | +| [DDOT Collector exporting directly to Datadog](#ddot-collector-exporting-directly-to-datadog) | Include the `infraattributes` processor in every pipeline. On hosts, enable `allow_hostname_override`. On Fargate, supply platform resource attributes instead. | +| [Collector exporting through a gateway](#collector-exporting-through-a-gateway) | Detect host information in the node-level Collector and preserve those resource attributes through the gateway. | +| [OpenTelemetry Collector with the Datadog Exporter](#opentelemetry-collector-with-the-datadog-exporter) | Run a Collector on each host and use the `resourcedetection` processor with the detectors for your environment. | +| [Direct OTLP intake without an Agent or Collector](#direct-otlp-intake-without-an-agent-or-collector) | Set platform resource attributes instead of `host.name`. | -### Agent or DDOT Collector on the same host as your workload +### OTLP ingestion by the Datadog Agent -This applies to [OTLP ingestion by the Datadog Agent][11], the [DDOT Collector as a DaemonSet][9], the DDOT Collector on [Linux][14] and [Windows][15] hosts, and the DDOT Collector sidecar on [ECS Fargate][16] and [EKS Fargate][17]. - -Deploy the Agent or DDOT Collector on every host that generates OTLP telemetry. Sending telemetry from one host to an Agent on another host is not supported. +Deploy the Datadog Agent on every host that generates OTLP telemetry. Sending telemetry from one host to an Agent on another host is not supported. For setup instructions, see [OTLP Ingestion by the Datadog Agent][11]. If incoming telemetry has no valid hostname attributes, Datadog uses the Agent hostname. If you set `host.name`, `host.id`, or another hostname attribute, make its value match the Agent hostname to avoid duplicate hosts. When you do not control the attributes that your applications emit, set the `datadog.host.name` resource attribute to override hostname resolution explicitly. -The DDOT Collector's `infraattributes` processor adds infrastructure attributes and tags to OTLP telemetry. Include it in every signal pipeline. Because the DDOT Collector runs inside the Datadog Agent, hostname attributes on incoming telemetry can resolve to a different name than the Agent's, which makes a single node appear as two hosts. Enable `allow_hostname_override` to use the Agent hostname instead: +### DDOT Collector exporting directly to Datadog + +The DDOT Collector's `infraattributes` processor adds infrastructure attributes and tags to OTLP telemetry. Include it in every signal pipeline. The processor needs resource attributes that identify the source container. If infrastructure tags are missing, see [Infrastructure tags are missing from telemetry][10]. + +The rest of the configuration depends on whether the DDOT Collector runs on a host. + +#### Host-based deployments + +This applies to the DDOT Collector as a [DaemonSet][9], and on [Linux][14] and [Windows][15] hosts. + +Because the DDOT Collector runs inside the Datadog Agent, hostname attributes on incoming telemetry can resolve to a different name than the Agent's, which makes a single node appear as two hosts. Enable `allow_hostname_override` to use the Agent hostname instead: ```yaml processors: @@ -47,33 +56,38 @@ processors: allow_hostname_override: true ``` -On ECS Fargate and EKS Fargate, add the `resourcedetection` processor alongside `infraattributes` and set the detectors for your platform: `[env, ecs]` for ECS Fargate, or `[env, eks]` for EKS Fargate. +#### Fargate sidecar deployments + +This applies to the DDOT Collector on [ECS Fargate][16] and [EKS Fargate][17], where the Datadog Agent runs as a sidecar container in the same task or pod as your application. + +Fargate does not support host-based deployments, so the host guidance above does not apply. Supply the platform resource attributes that `infraattributes` needs instead: -The `infraattributes` processor needs resource attributes that identify the source container. If infrastructure tags are missing, see [Infrastructure tags are missing from telemetry][10]. +- On ECS Fargate, add the ECS resource detector to your OpenTelemetry SDK to provide the `aws.ecs.task.arn` attribute. +- On EKS Fargate, add the EKS resource detector to your SDK, or add the `resourcedetection` processor with the `[env, eks]` detectors to your Collector configuration. -### Node-level Collector sending to a gateway +### Collector exporting through a gateway -This applies to gateway deployments of the OpenTelemetry Collector with the Datadog Exporter, and the [DDOT Collector as a gateway on Kubernetes][18]. +This applies to gateway deployments of the OpenTelemetry Collector with the Datadog Exporter, and to the [DDOT Collector as a gateway on Kubernetes][18]. In a gateway deployment, the Collector that exports to Datadog does not run on the host that produced the telemetry. If host information is not attached before the data reaches the gateway, telemetry from many hosts can collapse onto the gateway's hostname, or each Collector pod can register as its own host. Detect host information in the node-level Collector, then configure the gateway to preserve those resource attributes instead of detecting them again. For the Datadog Exporter, use the **Kubernetes DaemonSet -> Gateway** configuration in [Datadog Exporter configuration](#datadog-exporter-configuration). If a gateway deployment reports the wrong host, see [Gateway collector not forwarding host metadata][19]. -### Collector on each host with the Datadog Exporter +### OpenTelemetry Collector with the Datadog Exporter -This applies to the [OpenTelemetry Collector with the Datadog Exporter][20] running on each host or as a Kubernetes DaemonSet. +This applies to the [OpenTelemetry Collector with the Datadog Exporter][20] exporting directly to Datadog, either on each host or as a Kubernetes DaemonSet. If your Collector forwards to a gateway, see [Collector exporting through a gateway](#collector-exporting-through-a-gateway) instead. Run a Collector on every host and add the `resourcedetection` processor with the detectors for your environment, as described in [Datadog Exporter configuration](#datadog-exporter-configuration). -### Direct OTLP intake without a host +### Direct OTLP intake without an Agent or Collector -This applies to [OTLP intake for serverless platforms][12], such as AWS Lambda, ECS Fargate, Azure Functions, and Cloud Run, and [OTLP intake for managed platforms][13]. +This applies to [OTLP intake for serverless platforms][12], such as AWS Lambda, ECS Fargate, Azure Functions, and Cloud Run, and to [OTLP intake for managed platforms][13]. These workloads have no host to identify. Set the cloud and platform resource attributes for your environment instead of relying on `host.name` for workload identification. Each platform requires a different set of attributes.
Host metadata sent to the OTLP intake endpoints does not populate the Infrastructure Host List.
-If you run the DDOT Collector as a sidecar on ECS Fargate or EKS Fargate rather than sending to an OTLP intake endpoint, follow [Agent or DDOT Collector on the same host as your workload](#agent-or-ddot-collector-on-the-same-host-as-your-workload). +If you run the DDOT Collector as a sidecar on ECS Fargate or EKS Fargate rather than sending to an OTLP intake endpoint, see [Fargate sidecar deployments](#fargate-sidecar-deployments). ## Datadog Exporter configuration diff --git a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md index f4a93427ea5..4407750cecc 100644 --- a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md +++ b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_daemonset.md @@ -976,4 +976,4 @@ View metrics from the DDOT Collector to monitor the Collector health. [55]: /containers/datadog_operator [56]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ [57]: https://github.com/DataDog/helm-charts/blob/main/charts/datadog-operator/README.md -[58]: /opentelemetry/config/hostname_tagging/#agent-or-ddot-collector-on-the-same-host-as-your-workload +[58]: /opentelemetry/config/hostname_tagging/#ddot-collector-exporting-directly-to-datadog diff --git a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md index 58b23628584..0b0a9ceb21f 100644 --- a/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md +++ b/hugo/content/en/opentelemetry/setup/ddot_collector/install/kubernetes_gateway.md @@ -1373,4 +1373,4 @@ To view your gateway pods: [9]: http://github.com/kubernetes-sigs/metrics-server [10]: /containers/guide/cluster_agent_autoscaling_metrics/?tab=helm [11]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/datadogextension -[12]: /opentelemetry/config/hostname_tagging/#node-level-collector-sending-to-a-gateway +[12]: /opentelemetry/config/hostname_tagging/#collector-exporting-through-a-gateway diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md b/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md index 9b8c50fb2e7..6d6ec928f06 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest/managed_platforms.md @@ -122,4 +122,4 @@ Sampling controls available in the Collector (tail-based sampling, probabilistic [15]: https://docs.mulesoft.com/monitoring/telemetry-exporter [16]: https://docs.retool.com/apps/guides/observability/performance-monitoring [17]: https://vercel.com/marketplace/datadog -[18]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-without-a-host +[18]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-without-an-agent-or-collector diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md index b469caf0479..165d5295497 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest/serverless.md @@ -214,4 +214,4 @@ The GCP Resource Detector SDK automatically populates: `cloud.account.id`, `clou [3]: /opentelemetry/setup/otlp_ingest/logs/ [4]: /opentelemetry/setup/otlp_ingest/metrics/ [5]: /opentelemetry/setup/otlp_ingest/managed_platforms/ -[6]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-without-a-host +[6]: /opentelemetry/config/hostname_tagging/#direct-otlp-intake-without-an-agent-or-collector diff --git a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md index 958d16a5065..9ac9b654b35 100644 --- a/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md +++ b/hugo/content/en/opentelemetry/setup/otlp_ingest_in_the_agent.md @@ -394,4 +394,4 @@ env: [5]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/receiver/otlpreceiver/config.md [6]: /agent/configuration/agent-configuration-files/ [10]: /opentelemetry/runtime_metrics/ -[11]: /opentelemetry/config/hostname_tagging/#agent-or-ddot-collector-on-the-same-host-as-your-workload +[11]: /opentelemetry/config/hostname_tagging/#otlp-ingestion-by-the-datadog-agent From 2bf2575c7bf0b7740e05a118728623880fa16f76 Mon Sep 17 00:00:00 2001 From: Brett Blue Date: Tue, 18 Aug 2026 18:08:08 -0600 Subject: [PATCH 5/6] Tighten hostname recommendation wording - Make the Datadog Exporter path explicitly exclusive in both the table label and the heading, so it does not overlap the gateway path. - Fix a self-contradictory sentence: setting datadog.host.name is itself setting an attribute, so it cannot be the remedy for not controlling emitted attributes. State the override directly instead. - Replace "these workloads have no host to identify" with what is actually true: these paths do not use a host-based Agent or Collector. --- .../en/opentelemetry/config/hostname_tagging.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/hugo/content/en/opentelemetry/config/hostname_tagging.md b/hugo/content/en/opentelemetry/config/hostname_tagging.md index b66a8c7bae8..9444d7f9305 100644 --- a/hugo/content/en/opentelemetry/config/hostname_tagging.md +++ b/hugo/content/en/opentelemetry/config/hostname_tagging.md @@ -29,14 +29,14 @@ The right configuration depends on how you send telemetry to Datadog. Find your | [OTLP ingestion by the Datadog Agent](#otlp-ingestion-by-the-datadog-agent) | Run an Agent on every host that generates telemetry. Omit hostname attributes, or set them to match the Agent hostname. | | [DDOT Collector exporting directly to Datadog](#ddot-collector-exporting-directly-to-datadog) | Include the `infraattributes` processor in every pipeline. On hosts, enable `allow_hostname_override`. On Fargate, supply platform resource attributes instead. | | [Collector exporting through a gateway](#collector-exporting-through-a-gateway) | Detect host information in the node-level Collector and preserve those resource attributes through the gateway. | -| [OpenTelemetry Collector with the Datadog Exporter](#opentelemetry-collector-with-the-datadog-exporter) | Run a Collector on each host and use the `resourcedetection` processor with the detectors for your environment. | +| [OpenTelemetry Collector with the Datadog Exporter sending directly to Datadog](#opentelemetry-collector-with-the-datadog-exporter-sending-directly-to-datadog) | Run a Collector on each host and use the `resourcedetection` processor with the detectors for your environment. | | [Direct OTLP intake without an Agent or Collector](#direct-otlp-intake-without-an-agent-or-collector) | Set platform resource attributes instead of `host.name`. | ### OTLP ingestion by the Datadog Agent Deploy the Datadog Agent on every host that generates OTLP telemetry. Sending telemetry from one host to an Agent on another host is not supported. For setup instructions, see [OTLP Ingestion by the Datadog Agent][11]. -If incoming telemetry has no valid hostname attributes, Datadog uses the Agent hostname. If you set `host.name`, `host.id`, or another hostname attribute, make its value match the Agent hostname to avoid duplicate hosts. When you do not control the attributes that your applications emit, set the `datadog.host.name` resource attribute to override hostname resolution explicitly. +If incoming telemetry has no valid hostname attributes, Datadog uses the Agent hostname. If you set `host.name`, `host.id`, or another hostname attribute, make its value match the Agent hostname to avoid duplicate hosts. To override hostname resolution explicitly, set the `datadog.host.name` resource attribute to the Agent hostname. ### DDOT Collector exporting directly to Datadog @@ -73,9 +73,9 @@ In a gateway deployment, the Collector that exports to Datadog does not run on t Detect host information in the node-level Collector, then configure the gateway to preserve those resource attributes instead of detecting them again. For the Datadog Exporter, use the **Kubernetes DaemonSet -> Gateway** configuration in [Datadog Exporter configuration](#datadog-exporter-configuration). If a gateway deployment reports the wrong host, see [Gateway collector not forwarding host metadata][19]. -### OpenTelemetry Collector with the Datadog Exporter +### OpenTelemetry Collector with the Datadog Exporter sending directly to Datadog -This applies to the [OpenTelemetry Collector with the Datadog Exporter][20] exporting directly to Datadog, either on each host or as a Kubernetes DaemonSet. If your Collector forwards to a gateway, see [Collector exporting through a gateway](#collector-exporting-through-a-gateway) instead. +This applies to the [OpenTelemetry Collector with the Datadog Exporter][20] running on each host or as a Kubernetes DaemonSet. If your Collector forwards to a gateway, see [Collector exporting through a gateway](#collector-exporting-through-a-gateway) instead. Run a Collector on every host and add the `resourcedetection` processor with the detectors for your environment, as described in [Datadog Exporter configuration](#datadog-exporter-configuration). @@ -83,7 +83,7 @@ Run a Collector on every host and add the `resourcedetection` processor with the This applies to [OTLP intake for serverless platforms][12], such as AWS Lambda, ECS Fargate, Azure Functions, and Cloud Run, and to [OTLP intake for managed platforms][13]. -These workloads have no host to identify. Set the cloud and platform resource attributes for your environment instead of relying on `host.name` for workload identification. Each platform requires a different set of attributes. +These ingestion paths do not use a host-based Agent or Collector. Set the cloud and platform resource attributes for your environment instead of relying on `host.name` for workload identification. Each platform requires a different set of attributes.
Host metadata sent to the OTLP intake endpoints does not populate the Infrastructure Host List.
From 40b594f8a0692599bb643769f078c5d57426ae5e Mon Sep 17 00:00:00 2001 From: Brett Blue <84536271+brett0000FF@users.noreply.github.com> Date: Thu, 20 Aug 2026 10:29:33 -0600 Subject: [PATCH 6/6] [DOCS-15393] Document APM hostname issue metric --- .../en/opentelemetry/config/hostname_tagging.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/hugo/content/en/opentelemetry/config/hostname_tagging.md b/hugo/content/en/opentelemetry/config/hostname_tagging.md index 9444d7f9305..e49a65cbc86 100644 --- a/hugo/content/en/opentelemetry/config/hostname_tagging.md +++ b/hugo/content/en/opentelemetry/config/hostname_tagging.md @@ -89,6 +89,23 @@ These ingestion paths do not use a host-based Agent or Collector. Set the cloud If you run the DDOT Collector as a sidecar on ECS Fargate or EKS Fargate rather than sending to an OTLP intake endpoint, see [Fargate sidecar deployments](#fargate-sidecar-deployments). +## Diagnose hostname issues + +Datadog emits the `datadog.apm.hostname_issue` gauge when an APM trace hostname is missing, resembles an ephemeral Kubernetes pod, or differs from the hostname reported by the Datadog Agent. This diagnostic metric helps identify hostname configuration problems; it does not affect billing. + +A trace has at most one `issue_type`. Use the table to identify the problem and select the appropriate action: + +| `issue_type` | What it indicates | Recommended action | +|---|---|---| +| `pod_like_gateway_mismatch` | The trace hostname differs from the Agent hostname and resembles a Kubernetes pod name. | Follow the [gateway recommendations](#collector-exporting-through-a-gateway). Detect the Kubernetes node in the node-level Collector and preserve those resource attributes through the gateway. | +| `gateway_hostname_mismatch` | The trace hostname differs from the Agent hostname. | Follow the [gateway recommendations](#collector-exporting-through-a-gateway) and preserve hostname resource attributes through the gateway. | +| `empty_hostname` | Datadog did not receive a usable hostname for the trace. | Follow the [recommendation for your ingestion path](#hostname-recommendations) and provide the required host or platform resource attributes. | +| `pod_like_hostname` | The trace hostname resembles an ephemeral Kubernetes pod name. | Configure resource detection for your [ingestion path](#hostname-recommendations) so that telemetry identifies the node, host, or platform instead of the pod. | + +Available metric tags include `issue_type`, `host`, `env`, `service`, `version`, and `span_source`. Affected spans receive the same `issue_type` tag, which you can use to find example traces and inspect their resource attributes. + +The pod-like issue types use common Kubernetes pod naming patterns as a heuristic. After updating your configuration, inspect new traces to confirm that they no longer have the issue type. + ## Datadog Exporter configuration The Datadog Exporter uses the [resource detection processor][2] and the [Kubernetes attributes processor][3] to collect host and container resource attributes. Add the appropriate processors to the relevant metrics, traces, and logs pipelines.