PTP Instance Monitoring Parameters¶

StarlingX supports per-instance monitoring parameters that control holdover behavior and out-of-tolerance alarm thresholds for PTP instances. These parameters are configured using the --section monitoring option of the system ptp-instance-parameter-add command and are consumed by both the collectd PTP plugin and the ptp-notification service.

When applied, the parameters are written to the /etc/linuxptp/ptpinstance/instance-monitoring.conf file on each host. Because both collectd and ptp-notification read from this file, the holdover and offset threshold values are synchronized between platform alarming and PTP status notification.

Supported Parameters¶

The following parameters are supported in the monitoring section. All parameters are optional. Default values are used when a parameter is not explicitly configured.

Parameter	Instance Types	Default	Description
`holdover_seconds`	ptp4l, ts2phc, clock	14400	Duration in seconds before an instance transitions from holdover to freerun. See Holdover Behavior for details on how this interacts with upstream timing sources. Not used by `phc2sys` instances.
`locked_to_holdover_threshold_seconds`	ts2phc, clock	300	Minimum time in seconds an instance must be locked before a holdover transition is considered stable. See Holdover Behavior for details.
`offset_threshold_minor_nsec`	ptp4l, phc2sys	1000	Offset threshold in nanoseconds for raising a minor out-of-tolerance alarm.
`offset_threshold_major_nsec`	ptp4l, phc2sys	1000000	Offset threshold in nanoseconds for raising a major out-of-tolerance alarm.

Configure Monitoring Parameters¶

Use the system ptp-instance-parameter-add command with the --section monitoring option to set monitoring parameters on an instance.

Example: Set holdover and offset thresholds on a ptp4l instance

~(keystone_admin)]$ system ptp-instance-parameter-add <ptp4l-instance> \
    --section monitoring \
    holdover_seconds=30 \
    offset_threshold_minor_nsec=500 \
    offset_threshold_major_nsec=500000

Example: Set holdover parameters on a ts2phc instance

~(keystone_admin)]$ system ptp-instance-parameter-add <ts2phc-instance> \
    --section monitoring \
    holdover_seconds=200 \
    locked_to_holdover_threshold_seconds=100

Example: Set holdover parameters on a clock instance

~(keystone_admin)]$ system ptp-instance-parameter-add <clock-instance> \
    --section monitoring \
    holdover_seconds=201 \
    locked_to_holdover_threshold_seconds=101

After setting the parameters, apply the configuration.

~(keystone_admin)]$ system ptp-instance-apply

Verify the Configuration¶

After applying, verify the generated configuration file on the host.

~(keystone_admin)]$ cat /etc/linuxptp/ptpinstance/instance-monitoring.conf

The output shows one section per configured instance. Instances without explicit parameters will appear with their default values. For example:

[phcinst0]
holdover_seconds 14400
offset_threshold_major_nsec 1000000
offset_threshold_minor_nsec 1000

[ptpinstance1]
holdover_seconds 30
offset_threshold_major_nsec 500000
offset_threshold_minor_nsec 500

[tsinst0]
holdover_seconds 200
locked_to_holdover_threshold_seconds 100

[clock]
holdover_seconds 201
locked_to_holdover_threshold_seconds 101

Verify that collectd has loaded the values by checking the collectd log.

~(keystone_admin)]$ grep "monitoring_parameters" /var/log/collectd.log

Expected output:

info ptp plugin PTP instance ptpinstance1's monitoring_parameters:
    {'holdover_seconds': 30, 'offset_threshold_major_nsec': 500000,
    'offset_threshold_minor_nsec': 500}

Remove Monitoring Parameters¶

To remove a monitoring parameter and revert to the default value, use the system ptp-instance-parameter-delete command.

~(keystone_admin)]$ system ptp-instance-parameter-delete <instance> \
    --section monitoring \
    holdover_seconds=30

~(keystone_admin)]$ system ptp-instance-apply

Holdover Behavior¶

The holdover_seconds and locked_to_holdover_threshold_seconds parameters work together to control how instances transition between timing states.

For ts2phc and clock instances:

Locked: The instance is synchronized to its timing source.
Holdover: The timing source has been lost, and the instance has been locked for at least locked_to_holdover_threshold_seconds. The instance continues to maintain time using its internal oscillator.
Holdover-expired: The instance has been in holdover for longer than holdover_seconds. The collectd plugin sets the advertised clockClass to 140 to indicate degraded accuracy. A “GNSS/1PPS signal loss” alarm is raised with state holdover-expired.
Holdover-unstable: The timing source was lost before locked_to_holdover_threshold_seconds was reached. The instance transitions directly to freerun (clockClass 248) rather than holdover, as the clock is not considered stable enough for holdover. A “GNSS/1PPS signal loss” alarm is raised with state holdover-unstable (freerun).

For ptp4l instances, the effective holdover time is the minimum of the instance’s own holdover_seconds and the holdover_seconds of its upstream timing source (ts2phc or clock instance). This ensures that the advertised clockClass accurately reflects the state of the full timing chain. The clockClass values advertised depend on whether the node is operating as a T-GM or T-BC:

Condition	T-GM clockClass	T-BC clockClass
Holdover time ≤ `holdover_seconds`	7	135
Holdover time > `holdover_seconds`	140	165
Holdover-unstable (freerun)	248	248

Out-of-Tolerance Alarms¶

The offset_threshold_minor_nsec and offset_threshold_major_nsec parameters control when out-of-tolerance alarms are raised for ptp4l and phc2sys instances.

When the measured time offset exceeds the minor threshold, a minor alarm is raised:

host=<hostname>.instance=<instance-name>.ptp=out-of-tolerance

When the offset exceeds the major threshold, the alarm severity is escalated to major. The alarm reason includes the configured thresholds for reference:

controller-0 Precision Time Protocol (PTP) clocking is out of tolerance
by more than 10 seconds (configured threshold: minor: 500 nsec, major: 500000 nsec)

Note

Out-of-tolerance monitoring is supported for both ptp4l and phc2sys instances, including phc2sys instances configured in HA mode. For HA phc2sys, the offset of the active source is used for threshold comparison.