netdata-otel-setup

Configure Netdata's otel-plugin to ingest OTLP/gRPC metrics and logs.

1|Updated Apr 17, 2026
One-click install
npx skills add https://github.com/netdata/skills --skill netdata-otel-setup
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: netdata-otel-setup
Source: https://github.com/netdata/skills/tree/main/skills/netdata-otel-setup
Command: npx skills add https://github.com/netdata/skills --skill netdata-otel-setup

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It helps you configure Netdata to receive OpenTelemetry data over OTLP/gRPC and get it correctly mapped into usable charts and logs instead of failing to ingest or appearing generic.

Core Features & Use Cases

  • Enable the OTLP/gRPC receiver: Turn on and verify Netdata’s built-in otel-plugin so collectors and SDKs can connect to the correct endpoint.
  • Configure and secure otel.yaml: Set the OTLP bind address, troubleshoot connectivity, and enable TLS (including mTLS with a client CA).
  • Map metrics to charts: Add metric mapping files under /etc/netdata/otel.d/v1/metrics/ so dimensions and chart shapes are meaningful; logs are ingested via the journal.
  • Debug ingestion issues: Use the troubleshooting workflow and optional log payload capture (store_otlp_json) to pinpoint where data is being dropped or misrendered.

Quick Start

Use netdata-otel-setup to configure /etc/netdata/otel.yaml for OTLP/gRPC ingestion and add metric mappings so your OTLP metrics render with proper chart dimensions.

Frequently Asked Questions about netdata-otel-setup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I configure Netdata to ingest OTLP metrics and logs via gRPC?▼

To ingest OTLP metrics and logs into Netdata, enable the built-in `otel-plugin` and edit the `/etc/netdata/otel.yaml` configuration file to set the OTLP/gRPC bind address. You must also add metric mapping files under `/etc/netdata/otel.d/v1/metrics/` to properly render chart dimensions.

How do I secure OpenTelemetry ingestion in Netdata using TLS or mTLS?▼

Secure OpenTelemetry ingestion in Netdata by applying TLS or mTLS settings within the `otel.yaml` configuration. You can configure the server certificate and enable mutual TLS by specifying a client CA to authenticate collectors and SDKs connecting to the OTLP/gRPC receiver endpoint.

Does Netdata support OpenTelemetry traces via the OTLP receiver?▼

Netdata does not support OpenTelemetry traces via the OTLP receiver. The `otel-plugin` supports Linux-only OTLP/gRPC reception for metrics starting at Netdata v2.7.0+ and logs at v2.9.0+, but trace ingestion is currently unsupported.

Why are my OpenTelemetry metrics showing up as generic charts in Netdata?▼

OpenTelemetry metrics appear as generic charts in Netdata when metric-to-chart mappings are missing. To resolve this, create specific metric mapping files under the `/etc/netdata/otel.d/v1/metrics/` directory so the dimensions and chart shapes are meaningful on the dashboard.

What is the best way to troubleshoot dropped OpenTelemetry data in Netdata?▼

The best way to troubleshoot dropped OpenTelemetry data in Netdata is to use the built-in troubleshooting workflow and enable the optional `store_otlp_json` log payload capture. This helps pinpoint where ingestion fails or data is misrendered before reaching the dashboard.

Can I use environment variable overrides for the Netdata OTLP receiver configuration?▼

Yes, you can use environment variable overrides to configure the Netdata OTLP receiver. When editing `/etc/netdata/otel.yaml` or `/opt/netdata/etc/netdata/otel.yaml`, optional environment variables can be applied to manage endpoint binding and connectivity settings dynamically.