10.1 Using evctl
evctl is eventd's native command-line client. Its normal operation has no
subcommand: the one positional argument is a PSPU observability query.
Quote the complete query. Without the quotes, the shell can split string
literals or expand * patterns before evctl sees them. Query syntax and
semantics remain those of PSPU §3.18–§3.27; evctl does not maintain a second
flag-based query language.
10.1.1 Commands and queries #
Exact standalone words such as help and version occupy the command
namespace. Anything whose first word is EVENTS, LOGS or METRIC, matched
without regard to ASCII case, is a query. This leaves room for administrative
commands without requiring the common query operation to be written as
evctl query ....
The query can instead be read from a UTF-8 file or standard input:
|
The default socket is /run/eventd/query.sock. --socket PATH selects a
nonstandard configured socket. The server obtains the caller from the Unix
socket peer token and performs every identifier and field access check; the
client never opens an eventd database or substitutes its own authorization
decision.
10.1.2 Output #
Data is written to standard output. Diagnostics and query errors are written to standard error, so redirecting or piping the result does not mix the two.
| Format | Selection | Use |
|---|---|---|
| Pretty | --format pretty (default) | One self-describing record per line, with terminal emphasis on field names. |
| JSON Lines | --format jsonl | One JSON object per record for text pipelines. Binary, extension and non-finite floating-point values use tagged objects rather than being discarded. |
| MessagePack | --format msgpack | A lossless binary sequence. Each record is preceded by a four-byte little-endian payload length. |
Records do not have a uniform schema. A field absent from one line is not necessarily absent from later lines. Scripts should select the fields they need in the query or tolerate missing object keys.
10.1.3 Result commitment #
An ok response is not, by itself, a completed result. A non-streaming query
only succeeds when eventd sends end; a streaming query's initial result only
succeeds when eventd sends watch (PSPU §3.16). If eventd reports an error
before that point, every preceding record belongs to an invalid partial result
and must be discarded.
evctl therefore renders initial records into an anonymous temporary spool.
It publishes the spool to standard output only after end or watch. The
spool bounds heap use independently of the result count and has no pathname to
clean up after a crash. After watch, new records are written directly as they
arrive. Closing evctl, including with Ctrl-C, closes the query connection and
ends the watch.
As with every streaming client, a blocked output pipeline eventually applies socket backpressure. eventd may terminate that stream rather than allowing a slow observer to interfere with ingestion.