view release on metacpan or  search on metacpan

src_bin/iqbi-damiq  view on Meta::CPAN

die "iqbi-damiq: --require-xs given but the " . Algorithm::EventsPerSecond->backend . " backend is loaded, not XS\n"
	if $require_xs && Algorithm::EventsPerSecond->backend ne 'XS';

my $sukkal = Algorithm::EventsPerSecond::Sukkal->new(
	socket => $socket,
	( defined $window         ? ( window         => $window )         : () ),
	( defined $max_keys       ? ( max_keys       => $max_keys )       : () ),
	( defined $max_key_length ? ( max_key_length => $max_key_length ) : () ),
	( defined $idle_timeout   ? ( idle_timeout   => $idle_timeout )   : () ),
	( defined $sweep_interval ? ( sweep_interval => $sweep_interval ) : () ),
	( defined $max_clients    ? ( max_clients    => $max_clients )    : () ),
	( defined $mode           ? ( socket_mode    => $mode )           : () ),
);

if ($daemonize) {
	require POSIX;

	defined( my $pid = fork ) or die "iqbi-damiq: cannot fork: $!\n";
	exit 0 if $pid;
	POSIX::setsid() != -1  or die "iqbi-damiq: setsid failed: $!\n";
	defined( $pid = fork ) or die "iqbi-damiq: cannot fork: $!\n";
	exit 0 if $pid;

	chdir '/';
	open STDIN,  '<', '/dev/null';
	open STDOUT, '>', '/dev/null';
	open STDERR, '>', '/dev/null';
} ## end if ($daemonize)

my $pidfile_owner;
if ( defined $pidfile ) {
	open my $fh, '>', $pidfile
		or die "iqbi-damiq: cannot write pidfile $pidfile: $!\n";
	print $fh "$$\n";
	close $fh;
	$pidfile_owner = $$;
}

END {
	unlink $pidfile
		if defined $pidfile && defined $pidfile_owner && $$ == $pidfile_owner;
}

$SIG{INT} = $SIG{TERM} = sub { $sukkal->stop };
$SIG{HUP} = 'IGNORE';

printf "iqbi-damiq: serving %s (window=%ds, backend=%s)\n",
	$socket, $sukkal->{window}, Algorithm::EventsPerSecond->backend
	unless $daemonize;

$sukkal->run;

print "iqbi-damiq: shut down\n" unless $daemonize;

exit 0;

__END__

=head1 NAME

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

=head1 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

=head1 DESCRIPTION

iqbi-damiq ("She said 'it is fine!'") runs a
L<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
L<Algorithm::EventsPerSecond::Sukkal/PROTOCOL> 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 C<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; C<-d> for classic double-fork daemonization.

=head1 OPTIONS

=over 4

=item -s, --socket PATH

Unix socket path to listen on. Required.

=item -w, --window SECONDS

Averaging window used for every meter. Default 60.

=item --max-keys N

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

=item --max-key-length N

Maximum key length in bytes. Default 255.

=item --idle-timeout SECONDS

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

=item --sweep-interval SECONDS

Seconds between eviction sweeps. Default 30.

=item --max-clients N

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

=item -m, --mode OCTAL

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

=item -x, --require-xs

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

=item -d, --daemonize

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

=item -p, --pidfile PATH

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

=item -h, --help

Show usage and options.

=item -v, --version

Show the version.

=back