nioc/rrd-json-exporter repository overview

⁠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
  

  Copy

• 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
  

  Copy

Environment Variables

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