Smokeping_probes_IRTT(3)

📦
version 2.9.0 · 12 versions
, in alpine 3.23, alpine 3.24

🌸 NAME 🌸

okay bestie, this is Smokeping_probes_IRTT(3) — the manual page for Smokeping::probes::IRTT, which is literally a SmokePing probe for IRTT (https://github.com/peteheist/irtt) 💅✨

✨ SYNOPSIS ✨

here’s the whole config situation, and yes you need the vibes exactly like this:

        *** Probes ***

        +IRTT

        binary = /usr/local/bin/irtt # mandatory
        forks = 5
        offset = 50%
        step = 300
        timeout = 15
        tmpdir = /tmp/smokeping-irtt

        # The following variables can be overridden in each target section
        /^influx_.+/ = influx_location = In the basement
        dscp = 46
        extraargs = --ttl=32
        fill = rand
        hmac = opensesame
        interval = 1.5
        ipversion = 6
        length = 172
        localaddr = 192.168.1.10:63814
        metric = rtt
        pings = 5
        readfrom = irtt1
        readfrompollinterval = 2
        serverfill = rand
        sleep = 0.5
        writeto = irtt1

        # [...]

        *** Targets ***

        probe = IRTT # if this should be the default probe

        # [...]

        + mytarget
        # probe = IRTT # if the default probe is something else
        host = my.host
        /^influx_.+/ = influx_location = In the basement
        dscp = 46
        extraargs = --ttl=32
        fill = rand
        hmac = opensesame
        interval = 1.5
        ipversion = 6
        length = 172
        localaddr = 192.168.1.10:63814
        metric = rtt
        pings = 5
        readfrom = irtt1
        readfrompollinterval = 2
        serverfill = rand
        sleep = 0.5
        writeto = irtt1

🦋 DESCRIPTION 🦋

so this SmokePing probe uses IRTT (https://github.com/peteheist/irtt) to record network round-trip time (https://en.wikipedia.org/wiki/Round-trip_delay_time), one-way delay (https://en.wikipedia.org/wiki/End-to-end_delay), or IPDV (https://en.wikipedia.org/wiki/Packet_delay_variation) (jitter), and which one it records is based on the value of the metric variable. iconic behavior, honestly 🌈

plus, the probe has a results sharing feature that is giving main character energy: it lets you use results from a single IRTT run to record multiple metrics for a given host at the same time. one target is defined with the writeto variable set, which selects the name of a temporary file to save the IRTT output to. additional targets are defined with the readfrom variable set to the same value, which, instead of running IRTT, wait for the main target’s output to become available, then parse it to record the chosen metric from the same data. see the writeto and readfrom variables for more information, iykyk 🫶

🚨 WARNING 🚨

okay this part is serious, bestie. the results sharing feature (writeto and readfrom variables) requires the number of forks for the IRTT probe to be at least the total number of IRTT targets defined (regardless of whether they have writeto and readfrom set). otherwise, there can be a deadlock while readfrom targets wait for their corresponding writeto target to complete, which may never start. that is not the vibe 💀 set your forks correctly, fr fr.

💅 VARIABLES 💅

okay bestie, this is the part where you actually get to configure things. there's two flavors: probe-specific variables (they live up in the probe's own block) and target-specific ones (those go per-target, so you can vibe differently for each host). let's go 🫶

🎀 supported probe-specific variables 🎀

binary

where your irtt binary is chillin'.

Example value: /usr/local/bin/irtt

Default value: /usr/bin/irtt

bestie this setting is mandatory — no binary, no probe, periodt. 💀

forks

run this many concurrent processes at maximum

Example value: 5

Default value: 5

offset

so if you're running a bunch of probes at once, you probably don't want them all hitting your network at the exact same second, right? that's literally what offset is for — it shifts the point in time when each probe gets run. you give it a percentage of the total interval, or the word 'random', and if you don't set anything here it just inherits whatever the 'General' section says. key thing: this does NOT influence the rrds themselves, it's purely a matter of when data acquisition is initiated. (this variable is only applicable if the variable 'concurrentprobes' is set in the 'General' section.)

Example value: 50%

step

how long the base interval is that this probe should use, if it's different from the one in the 'Database' section. ⚠️ real talk: the step in the RRD files is fixed when they're originally generated, so if you change step afterwards you'll have to delete the old RRD files or somehow convert them. no take-backs. (this variable is only applicable if the variable 'concurrentprobes' is set in the 'General' section.)

Example value: 300

timeout

how long a single 'ping' takes at maximum

Example value: 15

Default value: 5

tmpdir

a temporary directory where files for writeto/readfrom get placed. 🗂️

Default value: /tmp/smokeping-irtt

🦋 supported target-specific variables 🦋

/^influx_.+/

this is a tag that gets sent to influxdb and has zero impact on the probe measurement. the tag name gets sent without the influx_ prefix — that part gets replaced with tag_ instead. tags are for filtering, iykyk.

Example value: influx_location = In the basement

dscp

the packet DSCP value to use (irtt client --dscp) — DSCP being differentiated services (https://en.wikipedia.org/wiki/Differentiated_services). it's the same as the classic one byte IP ToS field, except on the modern Internet typically only the lower 6 bits get used, and that's what we call the DSCP value. the upper two bits are reserved for ECN (https://en.wikipedia.org/wiki/Explicit_Congestion_Notification). hex is totally allowed if you prefix it with 0x. ✨

Example value: 46

extraargs

extra arguments for irtt client (see irtt-client(1)). 👀 be careful with extra arguments, because some of them can corrupt the results — so like, don't just throw stuff in there.

Example value: --ttl=32

fill

the fill to use in the payload for the client → server packet (irtt client --fill). the length variable has to be large enough so there's actually a payload to fill, bestie. use rand for random fill, or see irtt-client(1) for more options.

Example value: rand

hmac

the HMAC key to use when sending packets to the server (irtt client --hmac) — HMAC meaning hash-based message authentication code (https://en.wikipedia.org/wiki/Hash-based_message_authentication_code).

Example value: opensesame

interval

the interval between successive requests, in seconds (irtt client -i, but the unit is always seconds (s)).

WARNING 😭 if interval is increased to greater than 5 seconds, the timeout (which defaults to pings * 5 seconds + 1) must be modified so that SmokePing doesn't kill the probe prematurely. additionally, interval must not be increased such that pings * interval is greater than step. for example, at step=300 and pings=20, the interval must not be greater than 15 seconds, but should preferably be less to account for handshake and packet wait times.

Example value: 1.5

Default value: 1

ipversion

the IP version to use for packets (4 or 6, corresponding to irtt client -4 or irtt client -6). by default the IP version is chosen based on the supplied host variable.

Example value: 6

length

the length (size) of the packet (irtt client -l). the length includes IRTT headers, but not IP or UDP headers. the actual packet length is increased to accommodate the IRTT headers, if necessary. header size as of IRTT 0.9.0 as used in SmokePing is 48 bytes when writeto is set (since both monotonic and wall clock values are requested) and 40 bytes otherwise. math! 🧮

Example value: 172

localaddr

the local address to bind to when sending packets (irtt client --local). see irtt-client(1) Host formats for valid syntax.

Example value: 192.168.1.10:63814

metric

the metric to record, one of:

note that the send and receive metrics require accurate external system clock synchronization, otherwise the values from one will be abnormally high and the other will be abnormally low or even negative, in which case the value 0 will be given SmokePing. 💀

it is recommended to install ntp on both the SmokePing client and IRTT server. properly configured NTP may be able to synchronize time to within a few milliseconds, which is usually enough to provide useful results. PTP over a LAN may achieve microsecond-level accuracy. for best results between geographically remote hosts, GPS receivers may be used. since send_ipdv and receive_ipdv measure the variation in times between successive packets, and since rtt and ipdv use monotonic clock values on the client side only, external time synchronization is not required for these metrics. slay 🌈

Default value: rtt

pings

how many pings should be sent to each target, if different from the global value specified in the Database section. ⚠️ note that the number of pings in the RRD files is fixed when they're originally generated, and if you change this parameter afterwards, you'll have to delete the old RRD files or somehow convert them. same deal as step, no cap.

Example value: 5

readfrom

the name of a file to read results from, instead of running IRTT. use in combination with writeto to use the results from one IRTT run to record multiple metrics. the value becomes the name of a file in tmpdir, and must be the same as another target's setting for writeto. multiple targets may use the same value for readfrom, but writeto and readfrom may not both be set for a given target. 🚫

when readfrom is set, any variables that affect irtt client are ignored because IRTT isn't being invoked — including: dscp, extraargs, fill, hmac, interval, ipversion, length, localaddr and serverfill. those values are only relevant in the corresponding writeto target.

note that the host variable must still be defined for targets that define readfrom, otherwise the target won't be used. 👑

when using this feature, be sure to have at least as many forks for the IRTT probe as you have total IRTT targets defined. see the DESCRIPTION section for more information.

Example value: irtt1

readfrompollinterval

the integer interval in seconds on which to poll for results when readfrom is set. lower numbers let readfrom see the results a bit sooner, at the cost of higher CPU usage. polling doesn't begin until the soonest time at which the IRTT client could have terminated normally. ⏰

Example value: 2

Default value: 5

serverfill

the fill to use in the payload for the server → client packet (irtt client --sfill). the length variable has to be large enough to accommodate a payload. use rand for random fill, or see irtt-client(1) for more options.

Example value: rand

sleep

the amount of time to sleep before starting requests or processing results (a float in seconds). this may be used to avoid CPU spikes caused by invoking multiple instances of IRTT at the same time. 💤

Example value: 0.5

writeto

the name of a file to write results to after running IRTT. use in combination with readfrom to use the results from this IRTT run to record multiple metrics. the value becomes the name of a file in tmpdir, and any targets with readfrom set to the same value will use this target's results. there must be only one target with writeto set for a given file, and writeto and readfrom may not both be set for a given target. 🎯

when using this feature, be sure to have at least as many forks for the IRTT probe as you have total IRTT targets defined. see the DESCRIPTION section for more information.

Example value: irtt1

👑 AUTHORS 👑

Pete Heist <pete@heistp.net> — the icon who made this whole thing, give them their flowers 💐

okay that's the whole page bestie, you're officially an IRTT probe expert now, no cap 🧚✨ this was Smokeping_probes_IRTT(3), version 2.9.0, dated 2025-06-30 — go forth and ping responsibly 💜

📦 where this page comes from