OpenNTPD Input Plugin

This plugin gathers metrics from OpenNTPD using the ntpctl command.

Introduced in: Telegraf v1.12.0 Tags: server, network OS support: all

Global configuration options

Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See CONFIGURATION.md for more details.

Configuration

# Get standard NTP query metrics from OpenNTPD.
[[inputs.openntpd]]
  ## Run ntpctl binary with sudo.
  # use_sudo = false

  ## Location of the ntpctl binary.
  # binary = "/usr/sbin/ntpctl"

  ## Maximum time the ntpctl binary is allowed to run.
  # timeout = "5s"

Permissions

It’s important to note that this plugin references ntpctl, which may require additional permissions to execute successfully. Depending on the user/group permissions of the telegraf user executing this plugin, you may need to alter the group membership, set facls, or use sudo.

Group membership (recommended)

$ groups telegraf
telegraf : telegraf

$ usermod -a -G ntpd telegraf

$ groups telegraf
telegraf : telegraf ntpd

Sudo privileges

If you use this method, you will need the following in your telegraf config:

[[inputs.openntpd]]
  use_sudo = true

You will also need to update your sudoers file:

$ visudo
# Add the following lines:
Cmnd_Alias NTPCTL = /usr/sbin/ntpctl
telegraf ALL=(ALL) NOPASSWD: NTPCTL
Defaults!NTPCTL !logfile, !syslog, !pam_session

Please use the solution you see as most appropriate.

Metrics

• openntpd

  • tags:
    • remote (remote peer address or hostname)
    • stratum (remote peer stratum)
    • state_prefix (ntpctl state indicator, e.g. * for active peer; omitted when absent)
  • fields:
    • delay (round trip delay to the remote peer in milliseconds; float)
    • jitter (mean deviation (jitter) for remote peer in milliseconds; float)
    • offset (mean offset (phase) to remote peer in milliseconds; float)
    • poll (polling interval in seconds; int)
    • next (number of seconds until the next poll; int)
    • wt (peer weight; int)
    • tl (peer trust level; int)

• openntpd_sensors (one metric per hardware/GPS sensor)

  • tags:
    • sensor (sensor device name, e.g. nmea0)
    • refid (sensor reference ID, e.g. GPS)
    • state_prefix (ntpctl state indicator, e.g. * for active sensor; omitted when absent)
  • fields:
    • wt (sensor weight; int)
    • gd (sensor good count; int)
    • st (sensor stratum; int)
    • next (seconds until next poll; int)
    • poll (polling interval in seconds; int)
    • offset (sensor offset in milliseconds; float)
    • correction (sensor correction in milliseconds; float)

• openntpd_status (one metric per gather, system-level summary)

  • fields:
    • peers_valid (number of currently valid peers; int)
    • peers_total (total number of configured peers; int)
    • sensors_valid (number of currently valid sensors; int)
    • sensors_total (total number of configured sensors; int)
    • constraint_offset_s (constraint offset in seconds; int)
    • clock_synced (1 if the local clock is synced, 0 otherwise; int)
    • stratum (local clock stratum; int)

Example Output

openntpd,remote=194.57.169.1,stratum=2 tl=10i,poll=1007i,offset=2.295,jitter=3.896,delay=53.766,next=266i,wt=1i 1514454299000000000
openntpd_sensors,sensor=nmea0,refid=GPS,state_prefix=* wt=10i,gd=1i,st=0i,next=1i,poll=15i,offset=-0.673,correction=0.6 1514454299000000000
openntpd_status peers_valid=12i,peers_total=12i,sensors_valid=1i,sensors_total=1i,constraint_offset_s=-1i,clock_synced=1i,stratum=1i 1514454299000000000