OpenTelemetry

Plugin: otel.plugin Module: otel

Overview

This plugin enables the Netdata Agent to receive OpenTelemetry metrics and logs via the OTLP/gRPC protocol from any compatible source — collectors, SDKs, or instrumented applications.

Metrics are automatically visualized as Netdata charts with full alerting support. Logs are stored in systemd-compatible journal files and can be explored through the Netdata Logs tab.

The plugin listens on a configurable gRPC endpoint for incoming OTLP data.

Incoming metrics are mapped to Netdata charts using YAML mapping rules placed in the chart configs directory (default /etc/netdata/otel.d/v1/metrics/). Each file can contain entries that match metrics by instrumentation scope and metric name, and control how data point attributes translate to chart instances and dimensions. Per-metric overrides for the collection interval and grace period are also supported. Without a matching rule, the plugin creates charts using default settings. Charts with no incoming data are automatically expired and removed.

Mapping file option	Description
instrumentation_scope.name	Regex to match the instrumentation scope name
instrumentation_scope.version	Regex to match the instrumentation scope version
dimension_attribute_key	Data point attribute whose value becomes the dimension name
interval_secs	Per-metric collection interval override (1–3600 seconds)
grace_period_secs	Per-metric grace period override

Incoming logs are written to journal files with configurable rotation and retention policies.

This collector is only supported on the following platforms:

• Linux

This collector only supports collecting metrics from a single instance of this integration.

Default Behavior

Auto-Detection

The plugin starts automatically and listens on 127.0.0.1:4317 for incoming OTLP/gRPC connections.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

Metrics

Metrics are dynamically created based on the OpenTelemetry data received. The specific metrics depend on the OTLP sources sending data to the plugin.

Alerts

There are no alerts configured by default for this integration.

Setup

Prerequisites

OpenTelemetry data source

An OpenTelemetry Collector, SDK, or instrumented application configured to send OTLP data to the Netdata agent's gRPC endpoint.

Configuration

Options

The plugin is configured via otel.yaml in the Netdata configuration directory. Only the fields you want to change need to be specified.

Any option can also be overridden via environment variables with the NETDATA_OTEL_ prefix (highest priority). The variable name is the config option in all caps with dots replaced by underscores — e.g. endpoint.tls_cert_path becomes NETDATA_OTEL_ENDPOINT_TLS_CERT_PATH.

Config options

Option	Description	Default	Required
endpoint.path	gRPC endpoint to listen on for incoming OTLP data.	127.0.0.1:4317	no
endpoint.tls_cert_path	Path to TLS certificate file. Enables TLS when provided.		no
endpoint.tls_key_path	Path to TLS private key file. Required when TLS certificate is provided.		no
endpoint.tls_ca_cert_path	Path to TLS CA certificate file for client authentication.		no
metrics.chart_configs_dir	Directory containing metric mapping YAML files.	/etc/netdata/otel.d/v1/metrics/	no
metrics.interval_secs	Collection interval in seconds (1–3600). Defines the Netdata chart update frequency.	10	no
metrics.grace_period_secs	Grace period in seconds. After the last data point, the plugin waits this long before gap-filling.	60	no
metrics.expiry_duration_secs	Expiry duration in seconds. Charts with no data for this long are removed.	900	no
metrics.max_new_charts_per_request	Maximum new charts created per gRPC request.	100	no
logs.journal_dir	Directory to store journal files for ingested logs.		yes
logs.size_of_journal_file	Maximum file size before rotating to a new journal file.	100MB	no
logs.entries_of_journal_file	Maximum log entries per journal file.	50000	no
logs.duration_of_journal_file	Maximum time span within a single journal file.	2 hours	no
logs.number_of_journal_files	Maximum number of journal files to keep.	10	no
logs.size_of_journal_files	Maximum total size of all journal files.	1GB	no
logs.duration_of_journal_files	Maximum age of journal files.	7 days	no
logs.store_otlp_json	Store the complete OTLP JSON in each log entry.	no	no

metrics.chart_configs_dir

Each file defines how OTLP metrics are mapped to Netdata charts. Files can match metrics by instrumentation scope and name, set the dimension attribute key, and override timing parameters. The plugin ships stock mappings; user files in this directory take priority.

metrics.max_new_charts_per_request

Limits cardinality explosion from high-cardinality label combinations.

logs.store_otlp_json

Useful for debugging and reprocessing, but increases storage usage.

via File

The configuration file name for this integration is otel.yaml.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config otel.yaml

Examples

Basic configuration

Listen on default endpoint with default settings.

endpoint:
  path: "127.0.0.1:4317"
metrics:
  chart_configs_dir: /etc/netdata/otel.d/v1/metrics/
  interval_secs: 10
  grace_period_secs: 60
  expiry_duration_secs: 900
  max_new_charts_per_request: 100
logs:
  journal_dir: /var/log/netdata/otel-journals

Partial user override

Override only specific fields in the user config. All other settings are inherited from the stock config. Unknown fields are ignored for forward compatibility.

Config

endpoint:
  path: "0.0.0.0:4317"
logs:
  number_of_journal_files: 20
  duration_of_journal_files: "14 days"

Metric mapping file

Place YAML files like this in /etc/netdata/otel.d/v1/metrics/ to control how OTLP metrics are mapped to Netdata charts. This example maps metrics from the OpenTelemetry Collector hostmetrics receiver.

Config

metrics:
  "system.network.connections":
    - instrumentation_scope:
        name: .*hostmetricsreceiver.*networkscraper$
      dimension_attribute_key: state

  "system.cpu.utilization":
    - instrumentation_scope:
        name: .*hostmetricsreceiver.*cpuscraper$
      dimension_attribute_key: state

  "system.memory.usage":
    - instrumentation_scope:
        name: .*hostmetricsreceiver.*memoryscraper$
      dimension_attribute_key: state
      interval_secs: 5

TLS-enabled configuration

Listen with TLS enabled for secure connections.

Config

endpoint:
  path: "0.0.0.0:4317"
  tls_cert_path: /etc/netdata/ssl/cert.pem
  tls_key_path: /etc/netdata/ssl/key.pem
metrics:
  chart_configs_dir: /etc/netdata/otel.d/v1/metrics/
  interval_secs: 10
  grace_period_secs: 60
  expiry_duration_secs: 900
  max_new_charts_per_request: 100
logs:
  journal_dir: /var/log/netdata/otel-journals