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