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.