RRD JSON Exporter

Lightweight HTTP service written in Go that exposes data from .rrd (Round Robin Database) files as JSON.
It is designed to integrate seamlessly with Grafana (via the Infinity datasource), monitoring stacks, or any system that needs to consume RRD metrics (such as those produced by Munin) over HTTP.

Key features

• Lightweight (uses less than 20 MB of RAM)
• RRD parsing via rrdtool fetch
• JSON API endpoints
• Search for RRD files by regular expression with detailed description (node, plugin, field, and type)
• File‑level or bulk RRD export within time range
• Built‑in caching
• Secured with basic authentication

Installation

This can be used as docker container:

• as standalone service:

  docker run -it -p 9090:808080 --rm \
  -v $(pwd)/rrd:/app/rrd:ro \
  -e LOG_LEVEL=debug \
  -e CACHE_TTL_METRICS=60 \
  --name rrd-json-exporter nioc/rrd-json-exporter:latest

• in a docker-compose.yml file:

  services:
    rrd-json-exporter:
      image: nioc/rrd-json-exporter:latest
      container_name: rrd-json-exporter
      environment:
        LOG_LEVEL: debug
        # CACHE_TTL_LIST: 1800
        # CACHE_TTL_METRICS: 60
        # ROUND_STEP: 60
        # PORT: 8080
        # AUTH_USER: myuser
        # AUTH_PASS: mypassword
      volumes:
        - ./rrd:/app/rrd:ro
      ports:
        - 9090:8080
      restart: unless-stopped

Environment Variables

Variable	Default	Description
LOG_LEVEL	info	Logging verbosity (error, info, debug)
CACHE_TTL_LIST	1800	File name cache duration in seconds (/list)
CACHE_TTL_METRICS	60	Metrics cache duration in seconds (/metrics)
ROUND_STEP	300	Rounding from and to timestamps
PORT	8080	Port the exporter listens on in the container
AUTH_USER		User (basic authentication)
AUTH_PASS		Password (basic authentication)

NB: Basic authentication is only enabled if both the AUTH_USER and AUTH_PASS environment variables are provided.

Usage

API Endpoints

List RRD files

Request a list of all available RRD metric files or those matching a regular expression (provided in the optionnal query parameter filter)

GET /list?filter=docker

This returns a JSON array containing the available RRD metric files:

[
  "server-docker_cpu-proxy-g.rrd",
  "server-docker_cpu-nginx-g.rrd",
  "server-docker_memory-proxy-g.rrd",
  "server-docker_memory-nginx-g.rrd"
]

You can also send a query parameter details to get a description of each RRD file:

GET /list?filter=docker&details

[
  {
    "nodename": "server",
    "plugin": "docker_cpu",
    "field": "proxy",
    "type": "gauge",
    "name": "server-docker_cpu-proxy-g.rrd"
  },
  {
    "nodename": "server",
    "plugin": "docker_memory",
    "field": "proxy",
    "type": "gauge",
    "name": "server-docker_memory-proxy-g.rrd"
  }
]

Get all RRD metrics

Request all available RRD metrics

GET /metrics

This returns a JSON array containing all metrics:

[
  {
    "n": "server-docker_cpu-proxy-g",
    "t": 1769878800,
    "v": 1.9536137042
  },
  {
    "n": "server-docker_cpu-proxy-g",
    "t": 1769879100,
    "v": 2.1562561502
  },
  {
    "n": "server-docker_cpu-proxy-g",
    "t": 1769879400,
    "v": 1.2935769699
  }
]

With the following attributes:

• n: the name of the metric
• t: the Unix timestamp in seconds
• v: the value of the metric at that time

Get specific RRD metrics

Request a specific RRD metric by its filename

GET /metrics?rrd=filename.rrd

Request several specific RRD metrics by their file name

GET /metrics?rrd={filename1.rrd,filename2.rrd}

This returns a JSON object containing the requested metrics.

Get metrics within a time range

Request metric(s) for a specific time range between from and to (expressed in ms)

GET /metrics?rrd=filename.rrd&from=1770146257895&to=1770167857895

Error messages

In case of an error, the message has the following structure with proper HTTP status codes:

{
  "status": "error",
  "message": "RRD file not found",
  "details": "server-docker_cpu.rrd"
}

Grafana integration

Use the Infinity Datasource plugin.

Declare source

• Home > Connections > Data sources > Add new data source
• Select Infinity type
• Choose a name
• In URL, Headers & Params set Base URL to http://rrd-json-exporter:8080/ (according to the name of your container)

Use in dashboard

You can import the sample dashboard.

• Add a variable: Settings > Variables > New variable

  • Type: Query
  • Name: rrdfile
  • Data source: select the Infinity source created before
  • Type: JSON
  • Parser: JQ
  • Source: URL
  • Method: GET
  • URL: list
  • Multi-value: ✅

• Add a visualization with:

  • Data source: select the Infinity source created before
  • Type: JSON
  • Parser: JSONata
  • Source: URL
  • Format: Time Series
  • Method: GET
  • URL: metrics?rrd=${rrdfile}&from=${__from}&to=${__to}
  • In Parsing options & Result fields
    • add 3 colmuns:
      • selector: t, format as Time (UNIX s)
      • selector: v, format as Number
      • selector: n, format as String
  • [optionnal for multi metrics] Add a Partition by values transformation with n field
  • [optionnal for multi metrics] Add a Rename fields by regex transformation

Credits

• Nioc - Initial work

See also the list of contributors to this project.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details