Log locations

TimeKeeper logs information in multiple files, stored by default at these locations:

• Linux: /var/log/
• Windows: %ProgramFiles%\timekeeper\var\log

The default location can be overridden with the LOGDIR configuration option. A full path without spaces must be specified. To use the Windows default value, do not specify anything for the LOGDIR configuration option.

Files stored here include:

• timekeeper (timekeeper.log on Windows) - central place for logging alarms, general messages, state change information and administrative information
• timekeeper_$SOURCE.data - one file per configured source
• timekeeperclients/ - directory of per-host and per-source data files for each reporting client

Each source in timekeeper.conf will have a timekeeper_$SOURCE.data file that corresponds to the configured source number. The file contains sync information about that source over time. Similarly, each client file in the timekeeperclients/ directory will have sync information about each client’s source over time. All sources have the same log format regardless of source type.

File formats

Every update that TimeKeeper receives for a particular source is recorded in the relevant source file, one line per update. The data files for each client and each client’s source stored in timekeeperclients does the same, with one update per client sample, with the same data format in both locations.

The best way to visualize and understand the behavior is to refer to the “Visualizing data” section. The data is an open format so that users can work with the data with the tools they need. The log file format is as follows -

In most installations, the first two fields - the absolute timestamp and the offset from the time source - are all that is of interest. (The timestamp is from the source’s clock, not the local system clock. A positive offset means the local system clock is ahead of the source clock; negative, the local system clock is behind the source clock.) Once started and running properly this file should be growing as updates are received.

• Column 1: Absolute timestamp of the update, seconds since midnight January 1 1970 (also known as UNIX time)
• Column 2: Offset (in seconds) from the remote server or time source
• Column 3: Raw offset from remote side - pre-smoothing and adjustments
• Column 4: Internal TimeKeeper use
• Column 5: Clock correction factor for the TimeKeeper managed clock
• Column 6: Used to provide additional data with TimeKeeper GPS devices
• Column 7: Used to provide additional data with TimeKeeper GPS devices
• Column 8: Internal TimeKeeper use
• Column 9: Timestamp type - hardware/software/other timestamp source
• Column 10: Network delay - meaning depends on type of source
• Column 11: Raw network delay - meaning depends on type of source (for NTP/PTP this is the one-way trip time)
• Column 12: Time source, PTP, NTP, PPS or other
• Column 13: “Ideal” clock correction that if used would have minimized offsets over the previous few minutes
• Column 14: Model error over the model interval period
• Column 15: Source traceability information, see below.
• Column 16: Internal TimeKeeper use
• Column 17: Reported upstream source accuracy, if available
• Column 18: Internal TimeKeeper use
• Column 19: Internal TimeKeeper use

If this file is not being updated, it’s likely that firewalls are preventing receipt of network data, or there is some configuration issue reported in the timekeeper file.

The amount of detail available in each file will vary depending on the client. For some remote client types, the data available is limited. If the client is a TimeKeeper client, the data provided in that file will be more fully populated, giving you a better understanding of timing quality across the network.

Column 15 options include “PRI”, “AUX”, “MON”, “INV”, “UTC” and “HOL”. For reporting purposes, if this field includes the keyword “PRI”, it is the primary source by which the system's clock is being steered, otherwise it is marked “AUX”. “UTC” indicates that the source reports it is traceable to UTC. “MON” indicates that the source is marked MONITORONLY. “INV” indicates that sourcecheck has marked the source invalid. “HOL” denotes that a time source is in holdover.