class

Logarithm::JournaldLogSource

Inherits Logarithm::AbstractLogSource < Reference < Object

Log source that reads directly from systemd journald.

This class provides integration with systemd's journald service, allowing Logarithm to ingest logs directly from the system journal. It supports both historical reading (for training) and live monitoring.

Features

  • Direct systemd journal access via C API bindings
  • Resume reading from saved cursor positions
  • Time-based filtering with --since parameter
  • Automatic permission checking
  • Formatted log output compatible with other sources

Usage Examples

Basic Journal Monitoring

source = JournaldLogSource.new
channel = Channel(String).new(1000)

source.start(channel)
# Logs will be sent to channel...
source.stop

Training with Historical Data

source = JournaldLogSource.new(from_head: true)
channel = Channel(String).new(10000)

source.start(channel)
# All historical journal entries will be sent to channel

Time-Based Filtering

# Read entries from last 2 hours
source = JournaldLogSource.new(since: "2 hours ago")

# Read from specific timestamp
source = JournaldLogSource.new(since: "2024-01-01 12:00:00")

CLI Usage

# Monitor journal in real-time
logarithm monitor --journald

# Train on journal data from last 24 hours
logarithm train --journald --time 24h

# Train on journal data from specific time
logarithm train --journald --since "1 day ago"

Constructors

new(cursor_file : String = "", from_head : Bool = false, since : String = "")

Creates a new journald log source.

Parameters:

  • cursor_file: Path to save/read cursor for resuming (auto-generated if empty)
  • from_head: If true, read from journal beginning (for training); if false, tail for monitoring
  • since: Time filter (e.g., "1 hour ago", "2024-01-01 12:00:00")
Source

Instance methods

descriptions

Returns human-readable descriptions of this log source.

Used for logging and audit purposes to identify which sources are being monitored.

Returns: Array containing "systemd journal"

Source
start(channel : Channel(String))

Starts reading journal entries and sending them to the channel.

This method opens the journal, seeks to the appropriate position based on configuration, and begins sending formatted log entries to the channel. For training (from_head=true), it reads historical entries asynchronously. For monitoring (from_head=false), it continuously monitors for new entries.

Parameters:

  • channel: Channel to send formatted log lines to

Raises: IngestionError if journal cannot be accessed or opened

Source
stop

Stops the log source and cleans up resources.

This method should signal background fibers to stop and close any open file handles, network connections, or system resources. After calling stop, the source should be ready to start again.

Source