How to Inspect Kernel Clock Frequency, Tick Drift, and Jitter in Linux Using adjtimex

Maintaining microsecond-accurate timekeeping is essential for distributed databases, financial high-frequency trading platforms, cryptographic certificate timestamping, and cluster consensus algorithms (such as Raft or Paxos). While time synchronisation daemons like Chrony or NTPd continuously poll external stratum servers, the Linux kernel relies on an internal Phase-Locked Loop (PLL) or Frequency-Locked Loop (FLL) algorithm to adjust the local system clock without introducing abrupt, backward-stepping time jumps. When investigating persistent clock drift, diagnosing hardware crystal oscillator inaccuracies, or tuning real-time kernel tick rates, standard date utilities provide zero visibility into the kernel’s timekeeping loop. The adjtimex system call and command-line utility provide direct insight and administrative control over kernel tick rates, frequency offsets, and clock stability parameters in Linux.

Understanding Linux Kernel Timekeeping Architecture

The Linux kernel derives system time from hardware timer interrupts (PIT, HPET, or CPU TSC – Time Stamp Counter) combined with the Real-Time Clock (RTC). The kernel clock algorithm is defined by several core parameters exposed through the timex structure:

• Tick Rate (tick): The number of microseconds added to the system clock on every timer interrupt. On standard x86 systems running at 100 Hz timer frequency (USER_HZ = 100), the default tick is 10000 microseconds (10 milliseconds).
• Frequency Offset (freq): A scaled frequency adjustment value (in parts per million, PPM, shifted by 16 bits) used to speed up or slow down the clock smoothly to compensate for physical quartz crystal thermal drift.
• Tolerance (tolerance): The maximum permissible clock frequency error before the kernel considers the clock untrustworthy (standard maximum is 500 PPM).
• Estimated Error (esterror) and Maximum Error (maxerror): Cumulative error bounds calculated by the kernel since the last synchronization event.
• Phase Jitter (precision): Measures the short-term stability and resolution of the kernel timekeeping source in microseconds.

Installing adjtimex on Linux Distributions

The adjtimex command-line utility is available in the base package repositories of modern Linux distributions:

# Debian, Ubuntu, and Linux Mint
sudo apt update && sudo apt install -y adjtimex

# Fedora, RHEL, Rocky Linux, and CentOS
sudo dnf install -y adjtimex

# Arch Linux
sudo pacman -S adjtimex

Inspecting Kernel Timekeeping Parameters

Execute adjtimex with the -p (print) flag to dump the active kernel timekeeping variables:

sudo adjtimex -p

The command outputs a structured inventory of the kernel’s internal clock state:

         mode: 0
       offset: 12
    frequency: -1429812
     maxerror: 450
     esterror: 15
       status: 8193 (PLL | NANO)
time_constant: 6
    precision: 1
    tolerance: 32768000
         tick: 10000
     raw time:  1711200000s 123456us = 1711200000.123456

Interpreting Frequency Drift and Clock Status

Key parameters in the output provide direct clues regarding clock stability:

• Status Flags: PLL | NANO confirms that the kernel Phase-Locked Loop is disciplined in nanosecond resolution mode. If UNSYNC appears, the kernel clock is running free without valid NTP discipline.
• Frequency: A value of -1429812 represents raw frequency offset. Divide by 65536 to convert to parts per million (PPM): -1429812 / 65536 ≈ -21.8 PPM. This indicates the local oscillator naturally runs 21.8 microseconds fast every second and is being continuously slowed down by the kernel.
• Maxerror / Esterror: Quantifies synchronization confidence. High values (> 16000000 us) indicate synchronization has failed or the NTP daemon has been unreachable for hours.

Calculating Physical Oscillator Drift Rates

If you suspect physical hardware clock skew or thermal instability, adjtimex can benchmark the drift between the CPU clock and the CMOS battery-backed Real-Time Clock (RTC):

sudo adjtimex --compare=10

The utility compares the kernel clock to the CMOS RTC over ten consecutive 10-second intervals, outputting a linear regression drift estimate:

--- current --- -- suggested --
cmos sec diff  tick  freq   tick      freq
  10     0.000 10000 -1429812 10000  -1429812
  20     0.001 10000 -1429812 10000  -1390450

This empirical test highlights whether the hardware motherboard RTC is defective or losing charge.

Manually Adjusting Tick Rate and Frequency

In isolated test environments, air-gapped simulation networks, or legacy systems without internet access, administrators can manually slew the clock or adjust tick rates to compensate for known hardware skew:

# Adjust kernel tick duration by 5 microseconds per interrupt
sudo adjtimex --tick 10005

# Apply an explicit frequency offset in PPM
sudo adjtimex --frequency -1500000

Warning: Avoid manual adjustments on production servers running active Chrony or systemd-timesyncd services, as concurrent adjustments will cause the NTP daemon to fight the manual overrides.

Logging Clock Jitter for High-Precision Performance Audits

Automate system stability audits by logging jitter metrics during intensive computational stress testing:

#!/bin/bash
echo "Timestamp,Offset_us,Frequency_PPM,EstError_us" > clock_metrics.csv
for i in {1..10}; do
    RAW=$(sudo adjtimex -p)
    OFFSET=$(echo "$RAW" | awk '/offset:/ {print $2}')
    FREQ_RAW=$(echo "$RAW" | awk '/frequency:/ {print $2}')
    FREQ_PPM=$(echo "scale=2; $FREQ_RAW / 65536" | bc)
    ERROR=$(echo "$RAW" | awk '/esterror:/ {print $2}')
    echo "$(date +%s),$OFFSET,$FREQ_PPM,$ERROR" >> clock_metrics.csv
    sleep 2
done

Using adjtimex provides Linux systems administrators and embedded kernel developers with precise diagnostic visibility into low-level timekeeping loops, ensuring physical oscillator drift is accounted for and distributed systems maintain microsecond synchronisation integrity.