NAME

iqbi-damiq - a unix-socket daemon tracking per-key event rates

SYNOPSIS

iqbi-damiq -s <socket> [options]

iqbi-damiq -s /var/run/iqbi-damiq.sock
iqbi-damiq -s /var/run/iqbi-damiq.sock -w 300 --max-keys 500000
iqbi-damiq -s /var/run/iqbi-damiq.sock -d -p /var/run/iqbi-damiq.pid

DESCRIPTION

iqbi-damiq ("She said 'it is fine!'") runs a Algorithm::EventsPerSecond::Sukkal daemon: clients connect to the unix socket, mark events against keys of their choosing, and query the sliding-window rate, in-window count, and lifetime total per key. See "PROTOCOL" in Algorithm::EventsPerSecond::Sukkal for the line protocol.

A quick poke with socat:

printf 'MARK requests 5\nRATE requests\nQUIT\n' \
    | socat - UNIX:/var/run/iqbi-damiq.sock

Or MARKRATE to mark and read the rate back in a single command:

printf 'MARKRATE requests 5\nQUIT\n' \
    | socat - UNIX:/var/run/iqbi-damiq.sock

By default the daemon stays in the foreground, which suits systemd and similar supervisors; -d for classic double-fork daemonization.

OPTIONS

-s, --socket PATH

Unix socket path to listen on. Required.

-w, --window SECONDS

Averaging window used for every meter. Default 60.

--max-keys N

Maximum distinct keys tracked at once; 0 for unlimited. Default 100000.

--max-key-length N

Maximum key length in bytes. Default 255.

--idle-timeout SECONDS

Evict keys unmarked for this long; must be at least the window. Default is twice the window.

--sweep-interval SECONDS

Seconds between eviction sweeps. Default 30.

--max-clients N

Maximum simultaneous client connections; 0 for unlimited, the default.

-m, --mode OCTAL

Permissions for the socket file, e.g. 0770. Default is whatever the umask allows.

-x, --require-xs

Refuse to start unless the XS backend of Algorithm::EventsPerSecond is loaded, rather than silently falling back to pure Perl. For hosts where the pure-Perl backend's speed or memory use is not acceptable.

-d, --daemonize

Detach from the terminal: double-fork, setsid, chdir to /, and point std streams at /dev/null.

-p, --pidfile PATH

Write the daemon PID here after any daemonization; removed on exit.

-h, --help

Show usage and options.

-v, --version

Show the version.

SIGNALS

SIGTERM and SIGINT shut the daemon down cleanly, closing clients and unlinking the socket. SIGHUP is ignored.

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999