Skip to content

Commit 4e4fa13

Browse files
davidv1992davidv1992
committed
Added documentation on exporting metrics.
1 parent 5ef45ba commit 4e4fa13

File tree

2 files changed

+138
-0
lines changed

2 files changed

+138
-0
lines changed

‎docs/guide/exporting-metrics.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Exporting metrics
2+
3+
Statime supports exporting key operational metrics to an external [prometheus](https://prometheus.io/) instance.
4+
5+
## Installed from package
6+
7+
If statime was installed from the packages distributed by us, the first step is to enable the observation socket in the configuration. For this, add the following section to the configuration:
8+
```toml
9+
[observability]
10+
observation-path = "/var/run/statime/observe"
11+
```
12+
13+
After restarting statime, the metrics exporter can then be enabled with
14+
```sh
15+
sudo systemctl enable --now statime-metrics-exporter
16+
```
17+
18+
After enabling the metrics exporter, a prometheus metrics dataset will be served on `127.0.0.1:9975/metrics`
19+
20+
The dataset will look something like:
21+
```
22+
# HELP statime_uptime_seconds The time that statime has been running.
23+
# TYPE statime_uptime_seconds gauge
24+
# UNIT statime_uptime_seconds seconds
25+
statime_uptime_seconds{version="0.4.0",build_commit="1fb674074ece5c492327ddd9982bc38dc0fa766e",build_commit_date="2025-03-13"} 648.041376773
26+
# HELP statime_number_ports The amount of ports assigned.
27+
# TYPE statime_number_ports gauge
28+
statime_number_ports{clock_identity="9c:6b:00:05:17:21:00:00"} 1
29+
# HELP statime_quality_class The PTP clock class.
30+
# TYPE statime_quality_class gauge
31+
statime_quality_class{clock_identity="9c:6b:00:05:17:21:00:00"} 248
32+
# HELP statime_quality_accuracy The quality of the clock.
33+
# TYPE statime_quality_accuracy gauge
34+
statime_quality_accuracy{clock_identity="9c:6b:00:05:17:21:00:00"} 254
35+
# HELP statime_quality_offset_scaled_log_variance 2-log of the variance (in seconds^2) of the clock when not synchronized.
36+
# TYPE statime_quality_offset_scaled_log_variance gauge
37+
statime_quality_offset_scaled_log_variance{clock_identity="9c:6b:00:05:17:21:00:00"} 26880
38+
# HELP statime_priority_1 priority 1 used in the BMCA.
39+
# TYPE statime_priority_1 gauge
40+
statime_priority_1{clock_identity="9c:6b:00:05:17:21:00:00"} 128
41+
# HELP statime_priority_2 priority 2 used in the BMCA.
42+
# TYPE statime_priority_2 gauge
43+
statime_priority_2{clock_identity="9c:6b:00:05:17:21:00:00"} 128
44+
# HELP statime_steps_removed The number of paths traversed between this instance and the Grandmaster PTP instance.
45+
# TYPE statime_steps_removed gauge
46+
statime_steps_removed{clock_identity="9c:6b:00:05:17:21:00:00"} 1
47+
# HELP statime_offset_from_master_nanoseconds Time difference between a Master PTP Instance as calculated by the Slave instance.
48+
# TYPE statime_offset_from_master_nanoseconds gauge
49+
# UNIT statime_offset_from_master_nanoseconds nanoseconds
50+
statime_offset_from_master_nanoseconds{clock_identity="9c:6b:00:05:17:21:00:00"} -0.000000005820766091346741
51+
# HELP statime_mean_delay_nanoseconds Packet delay between a Master PTP Instance as calculated by the Slave instance.
52+
# TYPE statime_mean_delay_nanoseconds gauge
53+
# UNIT statime_mean_delay_nanoseconds nanoseconds
54+
statime_mean_delay_nanoseconds{clock_identity="9c:6b:00:05:17:21:00:00"} 0.00000012153759598731995
55+
# HELP statime_grandmaster_clock_quality_class The PTP clock class.
56+
# TYPE statime_grandmaster_clock_quality_class gauge
57+
statime_grandmaster_clock_quality_class{clock_identity="9c:6b:00:05:17:21:00:00",parent_clock_identity="00:0e:fe:ff:fe:03:00:51",parent_port_number="1"} 6
58+
# HELP statime_grandmaster_clock_quality_accuracy The quality of the clock.
59+
# TYPE statime_grandmaster_clock_quality_accuracy gauge
60+
statime_grandmaster_clock_quality_accuracy{clock_identity="9c:6b:00:05:17:21:00:00",parent_clock_identity="00:0e:fe:ff:fe:03:00:51",parent_port_number="1"} 32
61+
# HELP statime_grandmaster_clock_quality_offset_scaled_log_variance 2-log of the variance (in seconds^2) of the grandmaster clock when not synchronized.
62+
# TYPE statime_grandmaster_clock_quality_offset_scaled_log_variance gauge
63+
statime_grandmaster_clock_quality_offset_scaled_log_variance{clock_identity="9c:6b:00:05:17:21:00:00",parent_clock_identity="00:0e:fe:ff:fe:03:00:51",parent_port_number="1"} 29038
64+
# HELP statime_grandmaster_priority_1 priority 1 of the parent's grandmaster.
65+
# TYPE statime_grandmaster_priority_1 gauge
66+
statime_grandmaster_priority_1{clock_identity="9c:6b:00:05:17:21:00:00",parent_clock_identity="00:0e:fe:ff:fe:03:00:51",parent_port_number="1"} 0
67+
# HELP statime_grandmaster_priority_2 priority 2 of the parent's grandmaster.
68+
# TYPE statime_grandmaster_priority_2 gauge
69+
statime_grandmaster_priority_2{clock_identity="9c:6b:00:05:17:21:00:00",parent_clock_identity="00:0e:fe:ff:fe:03:00:51",parent_port_number="1"} 0
70+
# HELP statime_current_utc_offset_seconds Current offset from UTC in seconds.
71+
# TYPE statime_current_utc_offset_seconds gauge
72+
# UNIT statime_current_utc_offset_seconds seconds
73+
statime_current_utc_offset_seconds{clock_identity="9c:6b:00:05:17:21:00:00"} 37
74+
# HELP statime_upcoming_leap_seconds The amount of seconds the last minute of this will be.
75+
# TYPE statime_upcoming_leap_seconds gauge
76+
# UNIT statime_upcoming_leap_seconds seconds
77+
statime_upcoming_leap_seconds{clock_identity="9c:6b:00:05:17:21:00:00"} 60
78+
# HELP statime_time_traceable Whether the timescale is traceable to a primary reference.
79+
# TYPE statime_time_traceable gauge
80+
statime_time_traceable{clock_identity="9c:6b:00:05:17:21:00:00"} 0
81+
# HELP statime_frequency_traceable Whether the frequency determining the timescale is traceable to a primary reference.
82+
# TYPE statime_frequency_traceable gauge
83+
statime_frequency_traceable{clock_identity="9c:6b:00:05:17:21:00:00"} 0
84+
# HELP statime_ptp_timescale Whether the timescale of the Grandmaster PTP Instance is PTP.
85+
# TYPE statime_ptp_timescale gauge
86+
statime_ptp_timescale{clock_identity="9c:6b:00:05:17:21:00:00"} 0
87+
# HELP statime_time_source The source of time used by the Grandmaster PTP instance.
88+
# TYPE statime_time_source gauge
89+
statime_time_source{clock_identity="9c:6b:00:05:17:21:00:00"} 32
90+
# HELP statime_path_trace_enable 1 if path trace options is enabled, 0 otherwise.
91+
# TYPE statime_path_trace_enable gauge
92+
statime_path_trace_enable{clock_identity="9c:6b:00:05:17:21:00:00"} 1
93+
# HELP statime_path_trace_list list of clocks from grandmaster to local clock.
94+
# TYPE statime_path_trace_list gauge
95+
statime_path_trace_list{clock_identity="9c:6b:00:05:17:21:00:00",node="self"} 0
96+
# HELP statime_port_state The current state of the port.
97+
# TYPE statime_port_state gauge
98+
statime_port_state{clock_identity="9c:6b:00:05:17:21:00:00",port="1"} 9
99+
# HELP statime_mean_link_delay_nanoseconds The current mean link delay of the port.
100+
# TYPE statime_mean_link_delay_nanoseconds gauge
101+
# UNIT statime_mean_link_delay_nanoseconds nanoseconds
102+
# EOF
103+
```
104+
105+
## Installed through cargo or from source
106+
107+
When installed through cargo or from source, two things need to be done:
108+
- Enabling the observability socket in the statime configuration.
109+
- Configuring the system to run the statime-metrics-exporter as a service
110+
111+
The observability socket can be enabled by adding the following to the configuration:
112+
```toml
113+
[observability]
114+
observation-path = "/var/run/statime/observe"
115+
```
116+
117+
Next, configure your system to run the statime-metrics-exporter binay as a service. For systemd based systems, an example is provided below.
118+
```ini
119+
[Unit]
120+
Description=Statime metrics exporter
121+
Documentation=https://github.com/pendulum-project/statime
122+
After=statime.service
123+
Requires=statime.service
124+
Conflicts=
125+
126+
[Service]
127+
Type=simple
128+
Restart=always
129+
ExecStart=/usr/bin/statime-metrics-exporter
130+
Environment="RUST_LOG=info"
131+
RuntimeDirectory=statime-observe
132+
User=statime-observe
133+
Group=statime-observe
134+
135+
[Install]
136+
WantedBy=multi-user.target
137+
```

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ markdown_extensions:
3030
nav:
3131
- Guide:
3232
- guide/getting-started.md
33+
- guide/exporting-metrics.md
3334
- Man Pages:
3435
- statime(8): man/statime.8.md
3536
- statime.toml(5): man/statime.toml.5.md

0 commit comments

Comments
 (0)