1Smokeping_probes_IRTT(3)           SmokePing          Smokeping_probes_IRTT(3)
2
3
4

NAME

6       Smokeping::probes::IRTT - a SmokePing Probe for IRTT
7       <https://github.com/peteheist/irtt>
8

SYNOPSIS

10        *** Probes ***
11
12        +IRTT
13
14        binary = /usr/local/bin/irtt # mandatory
15        forks = 5
16        offset = 50%
17        step = 300
18        timeout = 15
19        tmpdir = /tmp/smokeping-irtt
20
21        # 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
39        # [...]
40
41        *** Targets ***
42
43        probe = IRTT # if this should be the default probe
44
45        # [...]
46
47        + 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

DESCRIPTION

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
75       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
85   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

VARIABLES

94       Supported probe-specific variables:
95
96       binary
97           The location of your irtt binary.
98
99           Example value: /usr/local/bin/irtt
100
101           Default value: /usr/bin/irtt
102
103           This setting is mandatory.
104
105       forks
106           Run this many concurrent processes at maximum
107
108           Example value: 5
109
110           Default value: 5
111
112       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
123           Example value: 50%
124
125       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
134           Example value: 300
135
136       timeout
137           How long a single 'ping' takes at maximum
138
139           Example value: 15
140
141           Default value: 5
142
143       tmpdir
144           A temporary directory in which to place files for writeto/readfrom.
145
146           Default value: /tmp/smokeping-irtt
147
148       Supported target-specific variables:
149
150       /^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
156           Example value: influx_location = In the basement
157
158       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
168           Example value: 46
169
170       extraargs
171           Extra arguments to "irtt client" (see irtt-client(1)). Be careful
172           with extra arguments, as some can corrupt the results.
173
174           Example value: --ttl=32
175
176       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
182           Example value: rand
183
184       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
189           Example value: opensesame
190
191       interval
192           The interval between successive requests, in seconds ("irtt client
193           -i", but the unit is always seconds (s)).
194
195           WARNING
196
197           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
205           Example value: 1.5
206
207           Default value: 1
208
209       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
214           Example value: 6
215
216       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
224           Example value: 172
225
226       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
230           Example value: 192.168.1.10:63814
231
232       metric
233           The metric to record, one of:
234
235           •   rtt: round-trip time <https://en.wikipedia.org/wiki/Round-
236               trip_delay_time>
237
238           •   send: one-way send delay <https://en.wikipedia.org/wiki/End-to-
239               end_delay> (requires external time synchronization)
240
241           •   receive: one-way receive delay
242               <https://en.wikipedia.org/wiki/End-to-end_delay> (requires
243               external time synchronization)
244
245           •   ipdv: IPDV
246               <https://en.wikipedia.org/wiki/Packet_delay_variation>
247               (instantaneous packet delay variation, or jitter)
248
249           •   send_ipdv: IPDV for sent packets
250
251           •   receive_ipdv: IPDV for received packets
252
253           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
268           Default value: rtt
269
270       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
277           Example value: 5
278
279       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
292           Note that the host variable must still be defined for targets that
293           define readfrom, otherwise the target won't be used.
294
295           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
299           Example value: irtt1
300
301       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
308           Example value: 2
309
310           Default value: 5
311
312       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
318           Example value: rand
319
320       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
325           Example value: 0.5
326
327       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
336           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
340           Example value: irtt1
341

AUTHORS

343       Pete Heist <pete@heistp.net>
344
345
346
3472.8.2                             2022-01-22          Smokeping_probes_IRTT(3)
Impressum