<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netdata-otel/otel-plugin/README.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netdata-otel/otel-plugin/metadata.yaml"
sidebar_label: "OpenTelemetry"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Collectors/Cloud and DevOps"
keywords: ['opentelemetry', 'otel', 'otlp', 'grpc', 'metrics', 'logs', 'observability']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
endmeta-->

# OpenTelemetry


<img src="https://netdata.cloud/img/opentelemetry.svg" width="150"/>


Plugin: otel.plugin
Module: otel

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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.

## 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`.


<details open><summary>Config options</summary>



| 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](#option-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](#option-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](#option-logs-store-otlp-json) | Store the complete OTLP JSON in each log entry. | no | no |

<a id="option-metrics-chart-configs-dir"></a>
##### 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.


<a id="option-metrics-max-new-charts-per-request"></a>
##### metrics.max_new_charts_per_request

Limits cardinality explosion from high-cardinality label combinations.


<a id="option-logs-store-otlp-json"></a>
##### logs.store_otlp_json

Useful for debugging and reprocessing, but increases storage usage.



</details>



#### via File

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


You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
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.

```yaml
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.


<details open><summary>Config</summary>

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

```
</details>

###### 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.


<details open><summary>Config</summary>

```yaml
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

```
</details>

###### TLS-enabled configuration

Listen with TLS enabled for secure connections.

<details open><summary>Config</summary>

```yaml
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

```
</details>



## Alerts

There are no alerts configured by default for this integration.


## Metrics

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


