NTP

Auto-Detection

Health Check

Built-in Metrics

Bleemeo monitors NTP (ntpd) through automatic service detection, an NTP service check, and built-in metrics read over the NTP control protocol.

chrony is detected as a service of its own; see Chrony. Both share one dashboard and one metric category.

Auto-Detection

We detect NTP by its process and the service check defaults to port 123. If auto-detected parameters are incorrect, you can override them manually.

Linux

sudo tee /etc/glouton/conf.d/99-ntp.conf > /dev/null << 'EOF'
service:
  # For an ntpd running outside a container
  - type: "ntp"
    address: "127.0.0.1"
    port: 123

  # For an ntpd running in a Docker container
  - type: "ntp"
    instance: "CONTAINER_NAME"
    port: 123
EOF

Windows

Create or edit the file C:\ProgramData\glouton\conf.d\99-ntp.conf:

service:
  - type: "ntp"
    address: "127.0.0.1"
    port: 123

Glouton automatically detects configuration changes.

Requirements

The control protocol has to be reachable. ntpd answers mode 6 queries from localhost out of the box, but a hardened /etc/ntp.conf (or /etc/ntpsec/ntp.conf) can refuse them. Make sure the agent’s address is not covered by a restrict line carrying noquery:

restrict 127.0.0.1
restrict 172.17.0.0 mask 255.255.0.0

Reload ntpd after the change.

Service Check

Glouton performs an NTP protocol check.

Metric	Description
service_status	Status of NTP

Built-in Metrics

Metric	Description
ntpq_system_offset_seconds	Estimated offset of the local clock as computed by ntpd

Metrics not Collected by Default

ntpd also reports one series per peer, carried by an ip label holding the peer’s address. On a host polling a large pool this is a lot of series for little benefit, so they are gathered but not sent unless you ask for them:

Metric	Description
ntpq_offset_seconds	Estimated offset to the NTP peer's clock
ntpq_delay_seconds	Round-trip delay to the NTP peer
ntpq_reach_perc	Percentage of the last 8 polls of the NTP peer that succeeded
ntpq_flash	NTP peer sanity checks failed

Add them with metric.allow_metrics; see Metrics Filtering.

metric:
  allow_metrics:
    - "ntpq_offset_seconds"
    - "ntpq_delay_seconds"
    - "ntpq_reach_perc"
    - "ntpq_flash"

Monitoring Troubleshooting

See Troubleshoot a Service Check or Missing Metrics for what applies to every service: finding the address and port Glouton really uses, what each check message means, and how to read the collection error — which does not appear in the agent logs at the default level.

The Service Check is not OK

The NTP check is an NTP request over UDP, and its answers are specific to the protocol. All of them turn the service critical, except Unknown response from NTP server which leaves it unknown. They do not all mean the same thing: the first three below are the NTP server answering and telling you something about itself — monitoring is working, the server is actually not usable — while the others are monitoring-side failures.

Status text	Cause	Fix
NTP server not (yet) synchronized	The server answers, but has no valid time source of its own — often just after a restart	Wait for it to settle; if it persists, check its upstream servers
Local time and NTP time does not match	The time returned by the server and the agent’s own clock differ by more than 10 seconds	Fix the clock on whichever side drifted
NTP server refused the request: ...	ntpd answered with a Kiss-o’-Death instead of the time: a restrict ... kod line refuses the agent, or its rate limit dropped the query. The message says which	Allow the agent’s address in restrict, or relax discard
No data received from server	Nothing is listening on UDP 123	Check that ntpd is running and bound to the address being checked
Unknown response from NTP server	Something that is not an NTP server answers on that port	Check what listens there
Connection timed out after 10 seconds	The packets are dropped	Open UDP 123 for the agent
Unable to resolve address "..."	The configured address does not resolve	Fix the configuration

Metrics are Missing

Reproduce what Glouton does, from the machine where the agent runs:

ntpq -c "rv 0" 127.0.0.1

What you see	Cause	Fix
timed out, nothing received	A restrict line refuses mode 6 queries from the agent	Remove noquery for the agent’s address
nothing, on a containerized ntpd	The container’s address is not reported by the runtime	The container must not use network_mode: none or container:<other>
no metric at all, but chrony is installed	The daemon is chrony, not ntpd	See Chrony
only the per-peer metrics missing	They are not collected by default	See Metrics not Collected by Default