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        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
38        # [...]
39
40        *** Targets ***
41
42        probe = IRTT # if this should be the default probe
43
44        # [...]
45
46        + 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

DESCRIPTION

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
73       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
83   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

VARIABLES

92       Supported probe-specific variables:
93
94       binary
95           The location of your irtt binary.
96
97           Example value: /usr/local/bin/irtt
98
99           Default value: /usr/bin/irtt
100
101           This setting is mandatory.
102
103       forks
104           Run this many concurrent processes at maximum
105
106           Example value: 5
107
108           Default value: 5
109
110       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
121           Example value: 50%
122
123       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
132           Example value: 300
133
134       timeout
135           How long a single 'ping' takes at maximum
136
137           Example value: 15
138
139           Default value: 5
140
141       tmpdir
142           A temporary directory in which to place files for writeto/readfrom.
143
144           Default value: /tmp/smokeping-irtt
145
146       Supported target-specific variables:
147
148       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
158           Example value: 46
159
160       extraargs
161           Extra arguments to "irtt client" (see irtt-client(1)). Be careful
162           with extra arguments, as some can corrupt the results.
163
164           Example value: --ttl=32
165
166       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
172           Example value: rand
173
174       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
179           Example value: opensesame
180
181       interval
182           The interval between successive requests, in seconds ("irtt client
183           -i", but the unit is always seconds (s)).
184
185           WARNING
186
187           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
195           Example value: 1.5
196
197           Default value: 1
198
199       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
204           Example value: 6
205
206       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
214           Example value: 172
215
216       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
220           Example value: 192.168.1.10:63814
221
222       metric
223           The metric to record, one of:
224
225           ·   rtt: round-trip time <https://en.wikipedia.org/wiki/Round-
226               trip_delay_time>
227
228           ·   send: one-way send delay <https://en.wikipedia.org/wiki/End-to-
229               end_delay> (requires external time synchronization)
230
231           ·   receive: one-way receive delay
232               <https://en.wikipedia.org/wiki/End-to-end_delay> (requires
233               external time synchronization)
234
235           ·   ipdv: IPDV
236               <https://en.wikipedia.org/wiki/Packet_delay_variation>
237               (instantaneous packet delay variation, or jitter)
238
239           ·   send_ipdv: IPDV for sent packets
240
241           ·   receive_ipdv: IPDV for received packets
242
243           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
258           Default value: rtt
259
260       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
267           Example value: 5
268
269       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
282           Note that the host variable must still be defined for targets that
283           define readfrom, otherwise the target won't be used.
284
285           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
289           Example value: irtt1
290
291       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
298           Example value: 2
299
300           Default value: 5
301
302       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
308           Example value: rand
309
310       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
315           Example value: 0.5
316
317       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
326           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
330           Example value: irtt1
331

AUTHORS

333       Pete Heist <pete@eventide.io>
334
335
336
3372.7.2                             2019-07-26          Smokeping_probes_IRTT(3)
Impressum