Skip to content

Commit 458bccd

Browse files
mx-psikayayarai
mx-psi
and
kayayarai
authored
[opentelemetry/guide] Add guide for collecting host metadata via semantic conventions (DataDog#21374)
* [opentelemetry/guide] Add guide for host metadata * Address linter * Address feedback * edit pass --------- Co-authored-by: Kari Halsted <kari.halsted@datadoghq.com>
1 parent 2a89a2a commit 458bccd

File tree

2 files changed

+103
-0
lines changed

2 files changed

+103
-0
lines changed

‎content/en/opentelemetry/guide/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ further_reading:
3535
{{< nextlink href="/opentelemetry/guide/otlp_delta_temporality/" >}}Producing Delta Temporality Metrics with OpenTelemetry{{< /nextlink >}}
3636
{{< nextlink href="/opentelemetry/guide/semantic_mapping/" >}}Mapping OpenTelemetry resource attributes semantic conventions to Datadog conventions{{< /nextlink >}}
3737
{{< nextlink href="/opentelemetry/guide/metrics_mapping/" >}}Mapping OpenTelemetry metrics conventions to Datadog conventions{{< /nextlink >}}
38+
{{< nextlink href="/opentelemetry/guide/host_metadata/" >}}Mapping OpenTelemetry semantic conventions to Infrastructure List host information{{< /nextlink >}}
3839
{{< nextlink href="/opentelemetry/guide/otlp_histogram_heatmaps/" >}}Visualizing OTLP Histograms as heatmaps{{< /nextlink >}}
3940
{{< nextlink href="/opentelemetry/guide/switch_from_processor_to_connector/" >}}Switching from Datadog Processor to Datadog Connector for OpenTelemetry APM Metrics{{< /nextlink >}}
4041
{{< /whatsnext >}}

‎content/en/opentelemetry/guide/host_metadata.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Mapping OpenTelemetry Semantic Conventions to Infrastructure List Host Information
3+
kind: guide
4+
further_reading:
5+
- link: "/opentelemetry/"
6+
tag: "Documentation"
7+
text: "OpenTelemetry Support in Datadog"
8+
---
9+
10+
<div class="alert alert-info">
11+
This feature is in beta. If you have any feedback, contact <a href="/help/">Datadog support</a>.
12+
</div>
13+
14+
## Overview
15+
16+
The Datadog exporter supports sending system information about your hosts to Datadog, which you can see in the [Infrastructure List][6]. You can send this information in OTLP through the ['Resource' field][1] as part of any of the existing signals. This is supported under any [deployment pattern][9] including gateway deploys.
17+
18+
Datadog uses [OpenTelemetry semantic conventions][2] to recognize system information about your hosts. Follow the instructions for [setting up for host metrics][3] to send the necessary metrics and resource attributes to Datadog. Alternatively, you can manually send this information in the way that best fits your infrastructure.
19+
20+
## Opting in to the feature
21+
22+
To opt into the **public beta**, set the `datadog.host.use_as_metadata` resource attribute to `true` in all OTLP payloads that contain information about hosts.
23+
24+
Resources populate the infrastructure list information if they have a [host-identifying attribute][10] and the `datadog.host.use_as_metadata` attribute set to `true`.
25+
26+
To explicitly declare what resources to use for metadata, add the Boolean resource attribute `datadog.host.use_as_metadata` to all resources that have relevant host information.
27+
28+
For example, to set this for all resources in metrics, traces, and logs, use the [transform processor][7] with the following configuration:
29+
30+
```yaml
31+
processors:
32+
transform:
33+
metric_statements:
34+
- context: resource
35+
statements:
36+
- set(attributes["datadog.host.use_as_metadata"], true)
37+
trace_statements:
38+
- context: resource
39+
statements:
40+
- set(attributes["datadog.host.use_as_metadata"], true)
41+
log_statements:
42+
- context: resource
43+
statements:
44+
- set(attributes["datadog.host.use_as_metadata"], true)
45+
```
46+
47+
Add this processor to the `processors` list of all your pipelines.
48+
49+
You must explicitly tag all your resources with a host-identifying attribute. This is done by default by the [recommended setup for host metrics][3].
50+
51+
## Supported conventions
52+
53+
The Datadog exporter supports both resource attribute-level semantic conventions and system metrics-level semantic conventions. Supported resource attribute semantic conventions are mainly under [the `host.` namespace][4] and [the `os.` namespace][8]. All supported system metrics-level semantic conventions are under [the `system.` namespace][5].
54+
55+
### General system conventions
56+
57+
| Semantic convention | Type | In-app field |
58+
|---------------------------------------------|--------------------|--------------|
59+
| [*Various host-identifying attributes*][10] | Resource attribute | Hostname |
60+
| `os.description` | Resource attribute | OS |
61+
62+
### CPU conventions
63+
64+
| Semantic convention | Type | In-app field |
65+
|-----------------------------|--------------------|--------------------|
66+
| `host.cpu.vendor.id` | Resource attribute | Vendor ID |
67+
| `host.cpu.model.name` | Resource attribute | Model Name |
68+
| `host.cpu.cache.l2.size` | Resource attribute | Cache Size |
69+
| `host.cpu.family` | Resource attribute | Family |
70+
| `host.cpu.model.id` | Resource attribute | Model |
71+
| `host.cpu.stepping` | Resource attribute | Stepping |
72+
| `system.cpu.logical.count` | System metric | Logical Processors |
73+
| `system.cpu.physical.count` | System metric | Cores |
74+
| `system.cpu.frequency` | System metric | MHz |
75+
76+
### Network conventions
77+
78+
| Semantic convention | Type | In-app field |
79+
|---------------------|--------------------|---------------------------|
80+
| `host.ip` | Resource attribute | IP Address & IPv6 Address |
81+
| `host.mac` | Resource attribute | Mac Address |
82+
83+
### Collecting these conventions with the OpenTelemetry Collector
84+
85+
To collect these conventions with the OpenTelemetry Collector, set up the [recommended setup for host metrics][3]. The host metrics receiver collects all the relevant metrics, while the resource detection processor collects all relevant resource attributes.
86+
87+
**Note:** You need to add these processors and receivers in the Collector running on the host that you want to monitor. A gateway host does not collect this information from remote hosts.
88+
89+
## Further reading
90+
91+
{{< partial name="whats-next/whats-next.html" >}}
92+
93+
[1]: https://opentelemetry.io/docs/concepts/glossary/#resource
94+
[2]: https://opentelemetry.io/docs/concepts/semantic-conventions/
95+
[3]: /opentelemetry/collector_exporter/host_metrics
96+
[4]: https://opentelemetry.io/docs/specs/semconv/resource/host/
97+
[5]: https://opentelemetry.io/docs/specs/semconv/system/system-metrics/
98+
[6]: /infrastructure/list/
99+
[7]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor#transform-processor
100+
[8]: https://opentelemetry.io/docs/specs/semconv/resource/os/
101+
[9]: https://opentelemetry.io/docs/collector/deployment/
102+
[10]: /metrics/open_telemetry/otlp_metric_types/?tab=sum#hostname-resolution

0 commit comments

Comments
 (0)