Exporting Reference

This reference guide provides comprehensive information about enabling, configuring, and monitoring Netdata's exporting engine for sending metrics to external time-series databases.

For a quick introduction, read our exporting metrics overview or start with enabling a connector.

Core Capabilities

The exporting engine features a modular structure that supports:

• Multiple connector instances running simultaneously
• Different update intervals per connector
• Custom filters per connector instance
• Metric resampling to reduce database congestion

:::info

When you enable the exporting engine, Netdata exports metrics starting from the restart time, not the entire historical database.

:::

Operation Modes

Netdata provides three data export modes:

:::tip

Choosing the Right Mode:

• Use as-collected if you're building monitoring around a time-series database and know how to convert units
• Use average for simpler long-term archiving that matches Netdata's visualization exactly

:::

Supported Connectors

How Metric Names Are Constructed

OpenTSDB and Graphite export dotted metric names. Prometheus scrape and remote write export context-based metric names with labels.

Flat-name connectors: OpenTSDB and Graphite

These connectors join their name components with dots, so the chart and dimension are visible directly in the metric name:

OpenTSDB: prefix.chart.dimension
Graphite: prefix.hostname.chart.dimension

• OpenTSDB sends the host as a separate tag (host=...).
• Graphite embeds the host in the dotted path: prefix.hostname.chart.dimension.

Example (OpenTSDB): netdata.system.cpu.user with a host=myhost tag.

OpenTSDB and Graphite preserve dots in chart and dimension names. They replace other non-alphanumeric characters with underscores.

Prometheus exports: scrape and remote write

For homogeneous charts, both methods join the prefix and the chart context with underscores, and carry the chart, family, and dimension as labels:

prefix_context{chart="...", family="...", dimension="..."}

• The chart context — the template shared by all charts of the same kind — is part of the metric name, not the individual chart ID or name.
• average appends the chart units and _average. The scrape endpoint can omit the units with hideunits=yes.
• sum appends _sum without the chart units.
• In as-collected mode, incremental and percentage-over-difference counters append _total. For charts produced by the Prometheus collector, Netdata does not append _total.
• For heterogeneous as-collected charts, the dimension moves into the metric name (prefix_context_dimension) and is omitted from the labels.
• Netdata sanitizes the context, units, and any dimension embedded in a Prometheus metric name, so dots and other unsupported characters become underscores. Chart, family, and dimension labels retain their label values. The configured prefix is used as provided.

Example (remote write): netdata_system_cpu_percentage_average{chart="system.cpu", dimension="user", family="cpu", instance="myhost"}.

For the complete naming rules — contexts, units, suffixes, and how to preview the exact metric names via the allmetrics endpoint — see the Prometheus reference.

Quick comparison

Both approaches respect the send names instead of ids setting: when enabled, Netdata uses human-friendly chart and dimension names; when disabled, it uses the raw system IDs. See the OpenTSDB connector options for the prefix and name settings.

Configuration Structure

Your exporting.conf file contains these configuration blocks:

[exporting:global]
    enabled = yes
    send configured labels = no
    send automatic labels = no
    update every = 10

[prometheus:exporter]
    send names instead of ids = yes
    send configured labels = yes
    send automatic labels = no
    send charts matching = *
    send hosts matching = localhost *
    prefix = netdata

[graphite:my_graphite_instance]
    enabled = yes
    destination = localhost:2003
    data source = average
    prefix = netdata
    hostname = my-name
    update every = 10
    buffer on failures = 10
    timeout ms = 20000
    send charts matching = *
    send hosts matching = localhost *
    send names instead of ids = yes
    send configured labels = yes
    send automatic labels = yes

[prometheus_remote_write:my_prometheus_remote_write_instance]
    enabled = yes
    destination = localhost
    remote write URL path = /receive

[kinesis:my_kinesis_instance]
    enabled = yes
    destination = us-east-1
    stream name = netdata
    aws_access_key_id = my_access_key_id
    aws_secret_access_key = my_aws_secret_access_key

[pubsub:my_pubsub_instance]
    enabled = yes
    destination = pubsub.googleapis.com
    credentials file = /etc/netdata/pubsub_credentials.json
    project id = my_project
    topic id = my_topic

[mongodb:my_mongodb_instance]
    enabled = yes
    destination = localhost
    database = my_database
    collection = my_collection

[json:my_json_instance]
    enabled = yes
    destination = localhost:5448

[opentsdb:my_opentsdb_plaintext_instance]
    enabled = yes
    destination = localhost:4242

[opentsdb:http:my_opentsdb_http_instance]
    enabled = yes
    destination = localhost:4242
    username = my_username
    password = my_password

[opentsdb:https:my_opentsdb_https_instance]
    enabled = yes
    destination = localhost:8082

Configuration Sections

Connector Types

Available connector types with optional modifiers:

• graphite | graphite:http | graphite:https
• opentsdb:telnet | opentsdb:http | opentsdb:https
• prometheus_remote_write | prometheus_remote_write:http | prometheus_remote_write:https
• json | json:http | json:https
• kinesis | pubsub | mongodb

Configuration Options

Basic Settings

Connection Settings

Destination Examples

IPv4 configuration:

destination = 10.11.14.2:4242 10.11.14.3:4242 10.11.14.4:4242

IPv6 and IPv4 combined:

destination = [ffff:...:0001]:2003 10.11.12.1:2003

Special destinations:

• Kinesis: AWS region (e.g., us-east-1)
• MongoDB: MongoDB URI
• Pub/Sub: Service endpoint

Filtering Options

:::important

Pattern matching follows first-match logic. Order matters when using negative patterns (!).

Example: !*child* *db* matches all *db* hosts except those containing *child*.

:::

Label Settings

Chart Filtering

Filter metrics through two methods:

1. Configuration file:

   textCopy

   [prometheus:exporter]
       send charts matching = system.*
   

2. URL parameter:

   textCopy

   http://localhost:19999/api/v1/allmetrics?format=shell&filter=system.*
   

HTTPS Support

For databases without native TLS/SSL support, configure a reverse proxy:

• Nginx reverse proxy setup

Performance Considerations

The exporting engine operates independently to avoid slowing down Netdata. However:

:::warning

Multiple connector instances running batches simultaneously can consume significant CPU resources. Configure different update intervals to prevent synchronization.

:::

Monitoring the Exporting Engine

Netdata provides five monitoring charts under Netdata Monitoring:

Built-in Alerts

The exporting engine includes three automatic alerts:

Fallback Script

Netdata includes nc-exporting.sh for:

• Saving metrics to disk during database outages
• Pushing cached metrics when database recovers
• Monitoring/tracing/debugging metric generation