class

Arcana::Events::FileBackend

Inherits Arcana::Events::Backend < Reference < Object

Writes events as JSONL to a directory, one file per day.

Files:

<dir>/arcana-events-YYYY-MM-DD.jsonl (today, uncompressed) <dir>/arcana-events-YYYY-MM-DD.jsonl.gz (older days, compressed)

The record call is non-blocking: events go onto a buffered channel, drained by a background fiber that appends to the daily file. If the channel fills up, events are dropped and the drop count is logged to STDERR. (Better to drop than to block every Bus.send on disk I/O.)

Retention (via sweep!):

  • Files older than compress_age_days are gzipped and the uncompressed source is deleted.
  • Files (.jsonl or .jsonl.gz) older than retain_days are either deleted or moved to archive_dir (if set).
  • If max_size_mb is set and total dir size exceeds it, the oldest files are removed first until under the cap.

Constants

FILENAME_REGEX = /\Aarcana-events-(\d{4}-\d{2}-\d{2})\.jsonl(?:\.gz)?\z/

Constructors

new(log_dir : String, *, buffer_size : Int32 = 1024, compress_age_days : Int32 = 2, retain_days : Int32 = 90, archive_dir : String | Nil = nil, max_size_mb : Int32 | Nil = nil)
Source

Instance methods

archive_dir
Source
archive_dir=(archive_dir : String | Nil)
Source
close

Release resources; flush any buffered writes.

Source
compress_age_days
Source
compress_age_days=(compress_age_days : Int32)
Source
dropped
Source
log_dir
Source
log_dir=(log_dir : String)
Source
max_size_mb
Source
max_size_mb=(max_size_mb : Int32 | Nil)
Source
query(since : Time | Nil = nil, type : String | Nil = nil, subject : String | Nil = nil, limit : Int32 = 100) : Array(Event)

Query stored events. Filters are AND-combined.

Source
record(event : Event) : Nil

Record an event. Should not block on I/O — implementations may queue asynchronously and return immediately.

Source
retain_days
Source
retain_days=(retain_days : Int32)
Source
sweep!

Retention sweep — compresses old files and purges/archives very old ones. Safe to call periodically from any fiber.

Source