Add documentation and fallback to /host/ for getting the machine id (#21044)
vkalintiris committed
Oct 6, 2025 at 14:22 UTC
c9dd45eedf0d72d29800805398569cf47221b1fc
4 files changed
+96
-2
docs/.map/map.csv
+1
@@ -110,6 +110,7 @@ https://github.com/netdata/netdata/edit/master/src/collectors/README.md,Collecti
110
https://github.com/netdata/netdata/edit/master/src/collectors/REFERENCE.md,Collectors configuration,Published,Collecting Metrics,
111
https://github.com/netdata/agent-service-discovery/edit/master/README.md,Service discovery,Published,Collecting Metrics,
112
https://github.com/netdata/netdata/edit/master/src/collectors/statsd.plugin/README.md,StatsD,Published,Collecting Metrics,
113
+https://github.com/netdata/netdata/edit/master/src/crates/jf/otel-plugin/README.md,OpenTelemetry Metrics,Published,Collecting Metrics/OpenTelemetry,"Ingesting, storing and visualizing OpenTelemetry metrics",
114
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/README.md,Metrics Centralization Points,Published,Netdata Parents/Metrics Centralization Points,
115
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/configuration.md,Configuring Metrics Centralization Points,Published,Netdata Parents/Metrics Centralization Points,
116
https://github.com/netdata/netdata/edit/master/docs/observability-centralization-points/metrics-centralization-points/sizing-netdata-parents.md,Sizing Netdata Parents,Published,Netdata Parents/Metrics Centralization Points,
src/crates/jf/journal_file/src/file.rs
+12
-1
@@ -19,9 +19,20 @@ use std::backtrace::Backtrace;
19
20
use crate::value_guard::ValueGuard;
21
22
+fn read_host_file(filename: &str) -> Result<String> {
23
+ match std::fs::read_to_string(filename) {
24
+ Ok(contents) => Ok(contents),
25
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
26
+ let filename = format!("/host/{}", filename);
27
+ Ok(std::fs::read_to_string(filename)?)
28
+ }
29
+ Err(e) => Err(e.into()),
30
+ }
31
+}
32
+
33
#[cfg(target_os = "linux")]
34
pub fn load_machine_id() -> Result<[u8; 16]> {
24
- let content = std::fs::read_to_string("/etc/machine-id")?;
35
+ let content = read_host_file("/etc/machine-id")?;
36
let decoded = hex::decode(content.trim()).map_err(|_| JournalError::UuidSerde)?;
37
let bytes: [u8; 16] = decoded.try_into().map_err(|_| JournalError::UuidSerde)?;
38
Ok(bytes)
src/crates/jf/otel-plugin/README.md
new
+82
@@ -0,0 +1,82 @@
1
+# OpenTelemetry Metrics (otel.plugin)
2
+
3
+`otel.plugin` is a [Netdata](https://github.com/netdata/netdata) external plugin,
4
+enabling users to ingest, store and visualize OpenTelemetry metrics in charts.
5
+
6
+## Configuration
7
+
8
+Edit the [otel.yml](https://github.com/netdata/netdata/blob/master/src/crates/jf/otel-plugin/configs/otel.yml)
9
+configuration file using `edit-config` from the Netdata
10
+[config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory),
11
+which is typically located under `/etc/netdata`.
12
+
13
+```bash
14
+cd /etc/netdata # Replace this path with your Netdata config directory
15
+sudo ./edit-config otel.yml
16
+```
17
+
18
+### gRPC Endpoint
19
+
20
+By default `otel.plugin` listens for incoming OTLP-formatted metrics on
21
+`localhost:4317` via gRPC. Users can set up a secure TLS connection by
22
+updating the TLS configuration in the `endpoint` section:
23
+
24
+```yaml
25
+endpoint:
26
+ # gRPC endpoint to listen on for OpenTelemetry data
27
+ path: "127.0.0.1:4317"
28
+
29
+ # Path to TLS certificate file (enables TLS when provided)
30
+ tls_cert_path: null
31
+
32
+ # Path to TLS private key file (required when TLS certificate is provided)
33
+ tls_key_path: null
34
+
35
+ # Path to TLS CA certificate file for client authentication (optional)
36
+ tls_ca_cert_path: null
37
+```
38
+
39
+### Metrics
40
+
41
+The `metrics` section allows users to specify the directory containing
42
+configuration files for mapping OpenTelemetry metrics to Netdata chart
43
+instances, and the number of metric samples the `otel.plugin` will use for
44
+detecting their collection interval:
45
+
46
+```yaml
47
+metrics:
48
+ # Directory with configuration files for mapping OTEL metrics to Netdata charts
49
+ # (relative paths are resolved based on Netdata's user configuration directory)
50
+ chart_configs_dir: otel.d/v1/metrics/
51
+
52
+ # Number of samples to buffer for collection interval detection
53
+ buffer_samples: 10
54
+```
55
+
56
+## Mapping OpenTelemetry metrics to Netdata chart instances
57
+
58
+Without an explicit mapping, the `otel.plugin` defaults to creating distinct
59
+chart instances based on the attributes of each data point in a metric. Users
60
+can place their YAML chart configuration files under `otel.d/v1/metrics` to
61
+override, or fine-tune, the default mapping.
62
+
63
+For each instrumentation scope and metric name, the configuration defines
64
+the attributes that the `otel.plugin` will use when creating new chart
65
+instances and dimension names.
66
+
67
+For example, the following bit from the
68
+[otel.d/v1/metrics/hostmetrics.yml](https://github.com/netdata/netdata/blob/master/src/crates/jf/otel-plugin/configs/otel.d/v1/metrics/hostmetrics-receiver.yml)
69
+ configuration file for the [hostmetrics](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/internal/scraper/networkscraper/documentation.md) receiver:
70
+```yaml
71
+select:
72
+ instrumentation_scope_name: hostmetricsreceiver.*networkscraper
73
+ metric_name: system.network.connections
74
+extract:
75
+ chart_instance_pattern: metric.attributes.protocol
76
+ dimension_name: metric.attributes.state
77
+```
78
+will apply to metrics whose instrumentation scope and metric names match the
79
+corresponding regular expressions specified in the values of the
80
+`instrumentation_scope_name` and `metric_name` keys. Similarly, the values of
81
+the `protocol` and `state` attributes of each data point in the matched metric
82
+will be used to create a new chart instance with the proper dimension names.
src/crates/jf/otel-plugin/src/netdata_chart.rs
+1
-1
@@ -148,8 +148,8 @@ impl NetdataChart {
148
let name = "";
149
let title = &self.metric_description;
150
let units = &self.metric_unit;
151
- let family = &self.metric_name;
151
let context = format!("otel.{}", &self.metric_name);
152
+ let family = context.clone();
153
let chart_type = if self.is_histogram() {
154
"heatmap"
155
} else {