Event is generated on the cluster host
: The `linuxptp-daemon` process in the PTP Operator-managed pod runs as a Kubernetes `DaemonSet` and manages the various `linuxptp` processes (`ptp4l`, `phc2sys`, and optionally for grandmaster clocks, `ts2phc`). The `linuxptp-daemon` passes the event to the UNIX domain socket.
Event is passed to the cloud-event-proxy sidecar
: The PTP plugin reads the event from the UNIX domain socket and passes it to the `cloud-event-proxy` sidecar in the PTP Operator-managed pod. `cloud-event-proxy` delivers the event from the Kubernetes infrastructure to Cloud-Native Network Functions (CNFs) with low latency.
Event is published
: The `cloud-event-proxy` sidecar in the PTP Operator-managed pod processes the event and publishes the event by using the PTP events REST API v2.
Consumer application requests a subscription and receives the subscribed event
: The consumer application sends an API request to the producer `cloud-event-proxy` sidecar to create a PTP events subscription. Once subscribed, the consumer application listens to the address specified in the resource qualifier and receives and processes the PTP events.
## Configuring the PTP fast event notifications publisher {#cnf-configuring-the-ptp-fast-event-publisher-v2_ptp-consumer}
To start using PTP fast event notifications for a network interface in your cluster, you must enable the fast event publisher in the PTP Operator `PtpOperatorConfig` custom resource (CR) and configure `ptpClockThreshold` values in a `PtpConfig` CR that you create.
**Prerequisites**
- You have installed the OpenShift Container Platform CLI (`oc`).
- You have logged in as a user with `cluster-admin` privileges.
- You have installed the PTP Operator.
**Procedure**
1. Modify the default PTP Operator config to enable PTP fast events.
1. Save the following YAML in the `ptp-operatorconfig.yaml` file:
```yaml
apiVersion: ptp.openshift.io/v1
kind: PtpOperatorConfig
metadata:
name: default
namespace: openshift-ptp
spec:
daemonNodeSelector:
node-role.kubernetes.io/worker: ""
ptpEventConfig:
enableEventPublisher: true (1)
```
1. Enable PTP fast event notifications by setting `enableEventPublisher` to `true`.
2. Update the `PtpOperatorConfig` CR:
```terminal
$ oc apply -f ptp-operatorconfig.yaml
```
2. Create a `PtpConfig` custom resource (CR) for the PTP enabled interface, and set the required values for `ptpClockThreshold` and `ptp4lOpts`. The following YAML illustrates the required values that you must set in the `PtpConfig` CR:
```yaml
spec:
profile:
- name: "profile1"
interface: "enp5s0f0"
ptp4lOpts: "-2 -s --summary_interval -4" (1)
phc2sysOpts: "-a -r -m -n 24 -N 8 -R 16" (2)
ptp4lConf: "" (3)
ptpClockThreshold: (4)
holdOverTimeout: 5
maxOffsetThreshold: 100
minOffsetThreshold: -100
```
1. Append `--summary_interval -4` to use PTP fast events.
2. Required `phc2sysOpts` values. `-m` prints messages to `stdout`. The `linuxptp-daemon` `DaemonSet` parses the logs and generates Prometheus metrics.
3. Specify a string that contains the configuration to replace the default `/etc/ptp4l.conf` file. To use the default configuration, leave the field empty.
4. Optional. If the `ptpClockThreshold` stanza is not present, default values are used for the `ptpClockThreshold` fields. The stanza shows default `ptpClockThreshold` values. The `ptpClockThreshold` values configure how long after the PTP master clock is disconnected before PTP events are triggered. `holdOverTimeout` is the time value in seconds before the PTP clock event state changes to `FREERUN` when the PTP master clock is disconnected. The `maxOffsetThreshold` and `minOffsetThreshold` settings configure offset values in nanoseconds that compare against the values for `CLOCK_REALTIME` (`phc2sys`) or master offset (`ptp4l`). When the `ptp4l` or `phc2sys` offset value is outside this range, the PTP clock state is set to `FREERUN`. When the offset value is within this range, the PTP clock state is set to `LOCKED`.
**Additional resources**
{._additional-resources}
- [Configuring linuxptp services as ordinary clock](/openshift-docs-markdown/networking/advanced_networking/ptp/configuring-ptp#configuring-linuxptp-services-as-ordinary-clock_configuring-ptp)
## PTP events REST API v2 consumer application reference {#ptp-events-consumer-application-v2_ptp-consumer}
PTP event consumer applications require the following features:
1. A web service running with a `POST` handler to receive the cloud native PTP events JSON payload
2. A `createSubscription` function to subscribe to the PTP events producer
3. A `getCurrentState` function to poll the current state of the PTP events producer
The following example Go snippets illustrate these requirements:
```go {title="Example PTP events consumer server function in Go"}
func server() {
http.HandleFunc("/event", getEvent)
http.ListenAndServe(":9043", nil)
}
func getEvent(w http.ResponseWriter, req *http.Request) {
defer req.Body.Close()
bodyBytes, err := io.ReadAll(req.Body)
if err != nil {
log.Errorf("error reading event %v", err)
}
e := string(bodyBytes)
if e != "" {
processEvent(bodyBytes)
log.Infof("received event %s", string(bodyBytes))
}
w.WriteHeader(http.StatusNoContent)
}
```
```go {title="Example PTP events createSubscription function in Go"}
import (
"github.com/redhat-cne/sdk-go/pkg/pubsub"
"github.com/redhat-cne/sdk-go/pkg/types"
v1pubsub "github.com/redhat-cne/sdk-go/v1/pubsub"
)
// Subscribe to PTP events using v2 REST API
s1,_:=createsubscription("/cluster/node/| Metric | Description | Example |
|---|---|---|
openshift_ptp_clock_class |
Returns the PTP clock class for the interface. Possible values for PTP clock class are 6 (LOCKED), 7 (PRC UNLOCKED IN-SPEC), 52 (PRC UNLOCKED OUT-OF-SPEC), 187 (PRC UNLOCKED OUT-OF-SPEC), 135 (T-BC HOLDOVER IN-SPEC), 165 (T-BC HOLDOVER OUT-OF-SPEC), 248 (DEFAULT), or 255 (SLAVE ONLY CLOCK). |
{node="compute-1.example.com",process="ptp4l"} 6 |
openshift_ptp_clock_state |
Returns the current PTP clock state for the interface. Possible values for PTP clock state are FREERUN, LOCKED, or HOLDOVER. |
{iface="CLOCK_REALTIME", node="compute-1.example.com", process="phc2sys"} 1 |
openshift_ptp_delay_ns |
Returns the delay in nanoseconds between the primary clock sending the timing packet and the secondary clock receiving the timing packet. | {from="master", iface="ens2fx", node="compute-1.example.com", process="ts2phc"} 0 |
openshift_ptp_ha_profile_status |
Returns the current status of the highly available system clock when there are multiple time sources on different NICs. Possible values are 0 (INACTIVE) and 1 (ACTIVE). |
{node="node1",process="phc2sys",profile="profile1"} 1 {node="node1",process="phc2sys",profile="profile2"} 0 |
openshift_ptp_frequency_adjustment_ns |
Returns the frequency adjustment in nanoseconds between 2 PTP clocks. For example, between the upstream clock and the NIC, between the system clock and the NIC, or between the PTP hardware clock (phc) and the NIC. |
{from="phc", iface="CLOCK_REALTIME", node="compute-1.example.com", process="phc2sys"} -6768 |
openshift_ptp_interface_role |
Returns the configured PTP clock role for the interface. Possible values are 0 (PASSIVE), 1 (SLAVE), 2 (MASTER), 3 (FAULTY), 4 (UNKNOWN), or 5 (LISTENING). |
{iface="ens2f0", node="compute-1.example.com", process="ptp4l"} 2 |
openshift_ptp_max_offset_ns |
Returns the maximum offset in nanoseconds between 2 clocks or interfaces. For example, between the upstream GNSS clock and the NIC (ts2phc), or between the PTP hardware clock (phc) and the system clock (phc2sys). |
{from="master", iface="ens2fx", node="compute-1.example.com", process="ts2phc"} 1.038099569e+09 |
openshift_ptp_offset_ns |
Returns the offset in nanoseconds between the DPLL clock or the GNSS clock source and the NIC hardware clock. | {from="phc", iface="CLOCK_REALTIME", node="compute-1.example.com", process="phc2sys"} -9 |
openshift_ptp_process_restart_count |
Returns a count of the number of times the ptp4l and ts2phc processes were restarted. |
{config="ptp4l.0.config", node="compute-1.example.com",process="phc2sys"} 1 |
openshift_ptp_process_status |
Returns a status code that shows whether the PTP processes are running or not. | {config="ptp4l.0.config", node="compute-1.example.com",process="phc2sys"} 1 |
openshift_ptp_threshold |
Returns values for HoldOverTimeout, MaxOffsetThreshold, and MinOffsetThreshold.
|
{node="compute-1.example.com", profile="grandmaster", threshold="HoldOverTimeout"} 5 |