/ 
Langertha-Raider-0.504
/ Langertha::Raider::Monitor

NAME

Langertha::Raider::Monitor - Internal event stream of one background command: every stdout line becomes a notification

VERSION

version 0.504

SYNOPSIS

my $monitor = Langertha::Raider::Monitor->new(
  id          => $tasks->next_id('monitor'),
  loop        => $app->loop,
  tasks       => $app->tasks,
  command     => 'tail -f build.log | grep --line-buffered ERROR',
  description => 'errors in build.log',
  timeout     => 300,
  recipient   => 'main',
);
my $error = $monitor->start;          # undef, or why it could not start

DESCRIPTION

Internal module. Its interface may change without notice.

One run of the monitor tool (ADR 0031): a command that runs in the background, in a process group of its own, with standard input from /dev/null. Each line it writes to standard output is an event; the lines that come close together ("batch_window") are delivered as one <task-notification> to the run that started the monitor ("notify" in Langertha::Raider::Tasks), with the summary Monitor event: "DESCRIPTION" and the lines in an <event> element. Standard error is not an event; it is kept for the notification that ends the monitor with a failure.

The monitor is an entry of the registry (kind monitor, monitor_N), and it ends in exactly one of these ways, each with its own notification:

  • The command exits: completed (exit code 0) or failed.

  • The deadline ("timeout") passes: the command is stopped, status killed, summary ... timed out after Ns, and a hint that it can be started again.

  • Too many events ("burst_limit" notifications within "burst_window" seconds, or "event_limit" in all): the command is stopped and the notification says so and what to do about it.

  • It is stopped from outside (kill_shell, the run that started it ended, raider leaves): killed.

id

command

description

Required: the registry ID (monitor_1), the command (run with bash -c) and the description the notifications show.

loop

tasks

Required: the application's loop and registry.

recipient

The run the events go to: main, or the agent ID of the subagent that started the monitor. Nothing is delivered once that subagent has ended.

tool_use_id

The call that started it, for the tool-use-id of the notifications.

working_directory

Where the command runs; raider's own directory without it.

stderr_file

A Path::Tiny the command's standard error is written to. Without one it is discarded.

timeout

Seconds the monitor may run (the caller has applied the limits of the tool: 5 minutes by default, at most 30, at most 10 without a person).

batch_window

Seconds the lines that follow the first of a batch are collected: 0.2.

burst_limit

burst_window

More than burst_limit notifications (20) within burst_window seconds (10) stop the monitor.

event_limit

More than this many event notifications (500) in all stop the monitor.

line_limit

batch_limit

A line is cut at line_limit characters (2000), a batch at batch_limit (8000), each with a note.

kill_grace

Seconds between SIGTERM and SIGKILL when the command is stopped.

clock

A code reference for the time the burst window is measured with.

on_end

Called with the monitor when it has ended.

start

my $error = $monitor->start;

Registers the entry, starts the command and the deadline. Returns undef, or the reason the command could not be started.

stop

$monitor->stop;                 # as asked from outside
$monitor->stop('timeout');      # timeout, burst, total

Ends the command: SIGTERM to its process group, SIGKILL after "kill_grace" seconds, and the monitor with a killed notification that names the reason. Does nothing once the monitor has ended.

span

How long the monitor runs, as the tool says it: 5m, 90s.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-raider/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

https://raudssus.de/