Prometheus Chrony Exporter

This is a Prometheus Exporter for Chrony NTP.

For most use-cases, simply download the the latest release.

You need a Go development environment. Then, simply run make to build the executable:

make

This uses the common prometheus tooling to build and run some tests.

You can build a Docker container with the included docker make target:

make promu
promu crossbuild -p linux/amd64 -p linux/arm64
make docker

This will not even require Go tooling on the host.

Because chrony only listens on the host localhost, you need to adjust the default chrony address

docker run \
  -d --rm \
  --name chrony-exporter \
  -p 9123:9123 \
  quay.io/superq/chrony-exporter \
  --chrony.address=host.docker.internal:323

A minimal invocation looks like this:

./chrony_exporter

Supported parameters include:

usage: chrony_exporter [<flags>]


Flags:
  -h, --[no-]help                Show context-sensitive help (also try --help-long and --help-man).
      --chrony.address="[::1]:323"  
                                 Address of the Chrony server.
      --chrony.timeout=5s        Timeout on requests to the Chrony server.
      --[no-]collector.tracking  Collect tracking metrics
      --[no-]collector.sources   Collect sources metrics
      --[no-]collector.sourcestats
                                 Collect sourcestats metrics
      --[no-]collector.sources.with-ntpdata  
                                 Extend sources with ntpdata metrics (requires socket connection)
      --[no-]collector.serverstats  
                                 Collect serverstats metrics
      --[no-]collector.clients   Collect clients metrics
      --[no-]collector.chmod-socket  
                                 Chmod 0666 the receiving unix datagram socket
      --[no-]collector.dns-lookups  
                                 do reverse DNS lookups
      --web.telemetry-path="/metrics"  
                                 Path under which to expose metrics.
      --[no-]web.systemd-socket  Use systemd socket activation listeners instead of port listeners (Linux only).
      --web.listen-address=:9123 ...  
                                 Addresses on which to expose metrics and web interface. Repeatable for multiple
                                 addresses.
      --web.config.file=""       Path to configuration file that can enable TLS or authentication. See:
                                 https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md
      --log.level=info           Only log messages with the given severity or above. One of: [debug, info, warn,
                                 error]
      --log.format=logfmt        Output format of log messages. One of: [logfmt, json]
      --[no-]version             Show application version.

To disable a collector, use --no-. (i.e. --no-collector.tracking)

By default, the exporter will bind on :9123.

In case chrony is configured to not accept command messages via UDP (cmdport 0) the exporter can use the unix command socket opened by chrony. In this case use the command line option --chrony.address=unix:///path/to/chronyd.sock to configure the path to the chrony command socket. On most systems chrony will be listenting on unix:///run/chrony/chronyd.sock. For this to work the exporter needs to run as root or the same user as chrony. When the exporter is run as root the flag collector.chmod-socket is needed as well.

--collector.clients summarizes chronyd's client log, the same data shown by chronyc clients, into a few aggregate metrics with no per-client labels, so the number of series stays the same no matter how many clients connect:

• chrony_clients_connected{protocol} counts the clients in the log, split into nts (clients that completed an NTS-KE handshake) and ntp (the rest).
• chrony_clients_last_ntp_hit_ago_seconds and chrony_clients_ntp_interval_seconds are histograms of how recently each client was seen and how often it polls.
• chrony_clients_ntp_drops is a histogram of how many NTP requests were dropped (rate limited) per client.

This needs chrony 4.0 or later. The command it uses reports NTS-KE statistics, which chronyd only gained with NTS support in 4.0. Older versions do not know the command and reject the request, so the scrape sets chrony_up to 0.

The client log size is set by clientloglimit in chrony.conf. This is a limit in bytes, 512 KiB by default, which chronyd uses to hold a power-of-two number of records, around 4096 with the default. When the log is full chronyd reuses the oldest records, so the connected count stops at that limit. Increase clientloglimit to track more clients, but note that it is real memory (up to 2 GB), so set it to match the number of clients you expect.

You can use Prometheus rules to pre-compute some values.

For example, an absolute bound on the clock accuracy can be computed from several metrics as documented in the Chrony man pages.

groups:
  - name: Chrony
    rules:
      - record: instance:chrony_clock_error_seconds:abs
        expr: >
          abs(chrony_tracking_last_offset_seconds)
          +
          chrony_tracking_root_dispersion_seconds
          +
          (0.5 * chrony_tracking_root_delay_seconds)

The Chrony Exporter supports TLS and basic authentication.

To use TLS and/or basic authentication, you need to pass a configuration file using the --web.config.file parameter. The format of the file is described in the exporter-toolkit repository.