1Smokeping_probes_IRTT(3) SmokePing Smokeping_probes_IRTT(3)
2
6 Smokeping::probes::IRTT - a SmokePing Probe for IRTT
7 <https://github.com/peteheist/irtt>
8
10 *** Probes ***
11 +IRTT
13 binary = /usr/local/bin/irtt # mandatory
15 forks = 5
16 offset = 50%
17 step = 300
18 timeout = 15
19 tmpdir = /tmp/smokeping-irtt
20 # The following variables can be overridden in each target section
22 /^influx_.+/ = influx_location = In the basement
23 dscp = 46
24 extraargs = --ttl=32
25 fill = rand
26 hmac = opensesame
27 interval = 1.5
28 ipversion = 6
29 length = 172
30 localaddr = 192.168.1.10:63814
31 metric = rtt
32 pings = 5
33 readfrom = irtt1
34 readfrompollinterval = 2
35 serverfill = rand
36 sleep = 0.5
37 writeto = irtt1
38 # [...]
40 *** Targets ***
42 probe = IRTT # if this should be the default probe
44 # [...]
46 + mytarget
48 # probe = IRTT # if the default probe is something else
49 host = my.host
50 /^influx_.+/ = influx_location = In the basement
51 dscp = 46
52 extraargs = --ttl=32
53 fill = rand
54 hmac = opensesame
55 interval = 1.5
56 ipversion = 6
57 length = 172
58 localaddr = 192.168.1.10:63814
59 metric = rtt
60 pings = 5
61 readfrom = irtt1
62 readfrompollinterval = 2
63 serverfill = rand
64 sleep = 0.5
65 writeto = irtt1
66
68 This SmokePing probe uses IRTT <https://github.com/peteheist/irtt> to
69 record network round-trip time <https://en.wikipedia.org/wiki/Round-
70 trip_delay_time>, one-way delay <https://en.wikipedia.org/wiki/End-to-
71 end_delay> or IPDV
72 <https://en.wikipedia.org/wiki/Packet_delay_variation> (jitter), based
73 on the value of the metric variable.
74 Additionally, the probe provides a results sharing feature, which
76 allows using results from a single IRTT run to record multiple metrics
77 for a given host at the same time. One target is defined with the
78 writeto variable set, which selects the name of a temporary file to
79 save the IRTT output to. Additional targets are defined with the
80 readfrom variable set to the same value, which, instead of running
81 IRTT, wait for the main target's output to become available, then parse
82 it to record the chosen metric from the same data. See the writeto and
83 readfrom variables for more information.
84 WARNING
86 The results sharing feature (writeto and readfrom variables) requires
87 the number of forks for the IRTT probe to be at least the total number
88 of IRTT targets defined (regardless of whether they have writeto and
89 readfrom set). Otherwise, there can be a deadlock while readfrom
90 targets wait for their corresponding writeto target to complete, which
91 may never start.
92
94 Supported probe-specific variables:
95 binary
97 The location of your irtt binary.
98 Example value: /usr/local/bin/irtt
100 Default value: /usr/bin/irtt
102 This setting is mandatory.
104 forks
106 Run this many concurrent processes at maximum
107 Example value: 5
109 Default value: 5
111 offset
113 If you run many probes concurrently you may want to prevent them
114 from hitting your network all at the same time. Using the probe-
115 specific offset parameter you can change the point in time when
116 each probe will be run. Offset is specified in % of total interval,
117 or alternatively as 'random', and the offset from the 'General'
118 section is used if nothing is specified here. Note that this does
119 NOT influence the rrds itself, it is just a matter of when data
120 acquisition is initiated. (This variable is only applicable if the
121 variable 'concurrentprobes' is set in the 'General' section.)
122 Example value: 50%
124 step
126 Duration of the base interval that this probe should use, if
127 different from the one specified in the 'Database' section. Note
128 that the step in the RRD files is fixed when they are originally
129 generated, and if you change the step parameter afterwards, you'll
130 have to delete the old RRD files or somehow convert them. (This
131 variable is only applicable if the variable 'concurrentprobes' is
132 set in the 'General' section.)
133 Example value: 300
135 timeout
137 How long a single 'ping' takes at maximum
138 Example value: 15
140 Default value: 5
142 tmpdir
144 A temporary directory in which to place files for writeto/readfrom.
145 Default value: /tmp/smokeping-irtt
147 Supported target-specific variables:
149 /^influx_.+/
151 This is a tag that will be sent to influxdb and has no impact on
152 the probe measurement. The tag name will be sent without the
153 "influx_" prefix, which will be replaced with "tag_" instead. Tags
154 can be used for filtering.
155 Example value: influx_location = In the basement
157 dscp
159 The packet DSCP
160 <https://en.wikipedia.org/wiki/Differentiated_services> value to
161 use ("irtt client --dscp"). This is the same as the classic one
162 byte IP ToS field, but on the modern Internet, typically only the
163 lower 6 bits are used, and this is called the DSCP value. The upper
164 two bits are reserved for ECN
165 <https://en.wikipedia.org/wiki/Explicit_Congestion_Notification>.
166 Hex may be used if prefixed by "0x".
167 Example value: 46
169 extraargs
171 Extra arguments to "irtt client" (see irtt-client(1)). Be careful
172 with extra arguments, as some can corrupt the results.
173 Example value: --ttl=32
175 fill
177 The fill to use in the payload for the client to server packet
178 ("irtt client --fill"). The length variable must be large enough so
179 there's a payload to fill. Use rand for random fill, or see
180 irtt-client(1) for more options.
181 Example value: rand
183 hmac
185 The HMAC <https://en.wikipedia.org/wiki/Hash-
186 based_message_authentication_code> key to use when sending packets
187 to the server ("irtt client --hmac").
188 Example value: opensesame
190 interval
192 The interval between successive requests, in seconds ("irtt client
193 -i", but the unit is always seconds (s)).
194 WARNING
196 If interval is increased to greater than 5 seconds, the timeout
198 (which defaults to pings * 5 seconds + 1) must be modified so that
199 SmokePing doesn't kill the probe prematurely. Additionally,
200 interval must not be increased such that pings * interval is
201 greater than step. For example, at step=300 and pings=20, the
202 interval must not be greater than 15 seconds, but should preferably
203 be less to account for handshake and packet wait times.
204 Example value: 1.5
206 Default value: 1
208 ipversion
210 The IP version to use for packets (4 or 6, corresponding to "irtt
211 client -4" or "irtt client -6"). By default the IP version is
212 chosen based on the supplied host variable.
213 Example value: 6
215 length
217 The length (size) of the packet ("irtt client -l"). The length
218 includes IRTT headers, but not IP or UDP headers. The actual packet
219 length is increased to accommodate the IRTT headers, if necessary.
220 Header size as of IRTT 0.9.0 as used in SmokePing is 48 bytes when
221 writeto is set (since both monotonic and wall clock values are
222 requested) and 40 bytes otherwise.
223 Example value: 172
225 localaddr
227 The local address to bind to when sending packets ("irtt client
228 --local"). See irtt-client(1) Host formats for valid syntax.
229 Example value: 192.168.1.10:63814
231 metric
233 The metric to record, one of:
234 • rtt: round-trip time <https://en.wikipedia.org/wiki/Round-
236 trip_delay_time>
237 • send: one-way send delay <https://en.wikipedia.org/wiki/End-to-
239 end_delay> (requires external time synchronization)
240 • receive: one-way receive delay
242 <https://en.wikipedia.org/wiki/End-to-end_delay> (requires
243 external time synchronization)
244 • ipdv: IPDV
246 <https://en.wikipedia.org/wiki/Packet_delay_variation>
247 (instantaneous packet delay variation, or jitter)
248 • send_ipdv: IPDV for sent packets
250 • receive_ipdv: IPDV for received packets
252 Note that the "send" and "receive" metrics require accurate
254 external system clock synchronization, otherwise the values from
255 one will be abnormally high and the other will be abnormally low or
256 even negative, in which case the value 0 will be given SmokePing.
257 It is recommended to install ntp on both the SmokePing client and
258 IRTT server. Properly configured NTP may be able to synchronize
259 time to within a few milliseconds, which is usually enough to
260 provide useful results. PTP over a LAN may achieve microsecond-
261 level accuracy. For best results between geographically remote
262 hosts, GPS receivers may be used. Since "send_ipdv" and
263 "receive_ipdv" measure the variation in times between successive
264 packets, and since "rtt" and "ipdv" use monotonic clock values on
265 the client side only, external time synchronization is not required
266 for these metrics.
267 Default value: rtt
269 pings
271 How many pings should be sent to each target, if different from the
272 global value specified in the Database section. Note that the
273 number of pings in the RRD files is fixed when they are originally
274 generated, and if you change this parameter afterwards, you'll have
275 to delete the old RRD files or somehow convert them.
276 Example value: 5
278 readfrom
280 The name of a file to read results from, instead of running IRTT.
281 Use in combination with writeto to use the results from one IRTT
282 run to record multiple metrics. The value will become the name of a
283 file in tmpdir, and must be the same as another target's setting
284 for writeto. Multiple targets may use the same value for readfrom,
285 but writeto and readfrom may not be both set for a given target.
286 When readfrom is set, any variables that affect "irtt client" are
287 ignored because IRTT is not being invoked, including: dscp,
288 extraargs, fill, hmac, interval, ipversion, length, localaddr and
289 serverfill. These values are only relevant in the corresponding
290 writeto target.
291 Note that the host variable must still be defined for targets that
293 define readfrom, otherwise the target won't be used.
294 When using this feature, be sure to have at least as many forks for
296 the IRTT probe as you have total IRTT targets defined. See the
297 "DESCRIPTION" section for more information.
298 Example value: irtt1
300 readfrompollinterval
302 The integer interval in seconds on which to poll for results when
303 readfrom is set. Lower numbers will allow readfrom to see the
304 results a bit sooner, at the cost of higher CPU usage. Polling does
305 not begin until the soonest time at which the IRTT client could
306 have terminated normally.
307 Example value: 2
309 Default value: 5
311 serverfill
313 The fill to use in the payload for the server to client packet
314 ("irtt client --sfill"). The length variable must be large enough
315 to accommodate a payload. Use "rand" for random fill, or see
316 irtt-client(1) for more options.
317 Example value: rand
319 sleep
321 The amount of time to sleep before starting requests or processing
322 results (a float in seconds). This may be used to avoid CPU spikes
323 caused by invoking multiple instances of IRTT at the same time.
324 Example value: 0.5
326 writeto
328 The name of a file to write results to after running IRTT. Use in
329 combination with readfrom to use the results from this IRTT run to
330 record multiple metrics. The value will become the name of a file
331 in tmpdir, and any targets with readfrom set to the same value will
332 use this target's results. There must be only one target with
333 writeto set for a given file, and writeto and readfrom may not be
334 both set for a given target.
335 When using this feature, be sure to have at least as many forks for
337 the IRTT probe as you have total IRTT targets defined. See the
338 "DESCRIPTION" section for more information.
339 Example value: irtt1
341
343 Pete Heist <pete@heistp.net>
3442.8.2 2023-01-21 Smokeping_probes_IRTT(3)