NAME
Langertha::Skeid::UsageStore::JsonLog - Append-only JSON usage store — one file per event, or one line per event
VERSION
version 0.003
DESCRIPTION
The recommended usage store. Writing an event is an append, so it cannot block the event loop on a database round-trip the way the DBI backends can, and an append-only file is the easiest thing to reconcile after an incident.
Reporting reads and aggregates the whole log in memory. That is fine for the volumes this is meant for and deliberately not optimised — if a deployment outgrows it, the answer is a real database, not an index on a directory of JSON files.
path
Required. Directory (mode dir) or file (mode file) the events are written to.
mode
dir (the default) writes one <id>.json per event, created exclusively, which never needs a lock and is safe with several writers. file appends one JSON line per event under an exclusive flock; any value other than dir behaves as file. The event id -- UTC time, process id, a per-process random nonce and a sequence number -- is stored in the event as id.
fsync
When true, an event's bytes are flushed and fsync'd to disk before store returns, at a throughput cost. Default off: ADR 0004 already accepts that one in-flight event is lost on a crash, and the kernel's own writeback covers the rest under normal operation. Opt in where a crash losing an already-answered request's event is unacceptable.
backend
Returns jsonlog.
prepare
Creates the target directory (or the file's parent directory). Called when the store is configured, not when an event is written.
disconnect
No-op — nothing is held open between writes.
store
my $res = $store->store($event);Writes one event and returns { ok => 1, id => $id }, or { ok => 0, error => … }. A write failure is reported, never thrown: losing a usage event must not also fail the request that was already served. The proxy logs such an answer at error level as a lost usage event.
report
my $report = $store->report(\%filters);Reads every event, applies the since / api_key_id / model filters, and aggregates totals plus per-key and per-model breakdowns. recent holds the newest limit events (default 20). Unreadable files and lines are skipped. The shape is described in "The store contract" in Langertha::Skeid::UsageStore.
SEE ALSO
Langertha::Skeid::UsageStore, Langertha::Skeid::UsageStore::DBI
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-skeid/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.