NTP

Auto-Detection

Health Check

Exporter Metrics

Bleemeo monitors NTP through automatic service detection with protocol service checks, and optionally through a third-party Prometheus exporter for detailed clock synchronization metrics.

Auto-Detection

Glouton automatically detects NTP instances running on the system.

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:
  - type: "ntp"
    address: "127.0.0.1"
    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.

Service Check

Glouton performs an NTP protocol check when the service listens on port 123.

Metric	Description
service_status	Status of NTP

Exporter Metrics

For detailed clock synchronization metrics such as offset and stratum, you can deploy the sapcc/ntp_exporter.

Prerequisites

• An NTP server reachable from the host (local or remote)
• Glouton agent installed on the same host
• Go toolchain (if building from source) or access to GitHub releases

Installing the Exporter

No special configuration is needed on the NTP server side.

Download the latest release from the ntp_exporter releases page, or install with Go:

go install github.com/sapcc/ntp_exporter@latest

Start the exporter, pointing it at an NTP server:

ntp_exporter --ntp.server=127.0.0.1

The exporter listens on port 9559 by default. Verify it is working:

curl http://localhost:9559/metrics

For production use, create a systemd service unit to manage the exporter process.

Glouton Configuration

Linux

sudo tee /etc/glouton/conf.d/99-ntp.conf > /dev/null << 'EOF'
metric:
  prometheus:
    targets:
      - url: "http://localhost:9559/metrics"
        name: "ntp"
        allow_metrics:
          - "ntp_stratum"
          - "ntp_offset_seconds"
          - "ntp_rtt_seconds"
          - "ntp_reference_timestamp_seconds"
          - "ntp_leap"
          - "ntp_scrape_valid"
EOF

Windows

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

metric:
  prometheus:
    targets:
      - url: "http://localhost:9559/metrics"
        name: "ntp"
        allow_metrics:
          - "ntp_stratum"
          - "ntp_offset_seconds"
          - "ntp_rtt_seconds"
          - "ntp_reference_timestamp_seconds"
          - "ntp_leap"
          - "ntp_scrape_valid"

Glouton automatically detects configuration changes.

Customize collected metrics

The metrics below are our recommended defaults. You can adjust the allow_metrics list to include any metric from the ntp_exporter GitHub repository, or use deny_metrics to exclude specific ones. See Metrics Filtering for details.

Metric	Description
ntp_stratum	NTP stratum level of the server
ntp_offset_seconds	Clock offset from the NTP server in seconds
ntp_rtt_seconds	Round-trip time to the NTP server in seconds
ntp_reference_timestamp_seconds	Timestamp of the last NTP update
ntp_leap	Leap indicator (0 = none, 1 = add second, 2 = delete second, 3 = alarm)
ntp_scrape_valid	Whether the last scrape of the NTP server was successful (1 = valid)

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 a real NTP request over UDP, and its answers are specific to the protocol. All of them turn the service critical, but they do not all mean the same thing: the first two below are the NTP server telling you something about itself — monitoring is working, the server is not usable — while the others are the usual 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
No data received from server	UDP port 123 is filtered, or nothing listens on it	Open UDP 123 for the agent
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

Beyond service_status, NTP metrics do not come from Glouton itself but from a third-party Prometheus exporter, scraped as described in Exporter Metrics above. If those metrics are missing, the exporter is the place to look — start by fetching its /metrics endpoint by hand, then check the Prometheus scraping configuration.