Logarithm::Systemd::JournalReader

High-level interface for reading systemd journal entries.

This class provides a safe, idiomatic Crystal interface for accessing systemd journal entries. It encapsulates all low-level C API calls and provides high-level methods for seeking, reading, and iterating through journal entries.

Core Concepts

Journal Navigation

The journal maintains a read position that advances with each next_entry call. Use seek methods to position the reader at different points in the journal.

Cursors

Cursors are opaque strings that uniquely identify journal entry positions. They enable resumable processing and can be persisted across application restarts.

Timestamps

The journal uses microsecond-precision timestamps. The seek_realtime method accepts Crystal Time objects and converts them automatically.

Basic Usage Patterns

Real-time Monitoring

reader = JournalReader.new
return unless reader.open

# Start from current entries
reader.seek_tail

# Monitor new entries
loop do
  if entry = reader.next_entry
    process_entry(entry)
  else
    sleep 0.1.seconds
  end
end

reader.close

Historical Data Processing

reader = JournalReader.new
return unless reader.open

# Read from last 24 hours
cutoff = Time.utc - 24.hours
reader.seek_realtime(cutoff)

while entry = reader.next_entry
  # Process historical entries
  analyze_entry(entry)
end

reader.close

Resumable Processing

reader = JournalReader.new
return unless reader.open

# Resume from saved position
if cursor = load_saved_cursor()
  reader.seek_cursor(cursor)
else
  reader.seek_head # Start from beginning
end

while entry = reader.next_entry
  process_entry(entry)

  # Save progress periodically
  if rand < 0.01 # 1% chance
    save_cursor(entry.cursor)
  end
end

reader.close

Advanced Usage

Batch Processing

reader = JournalReader.new
reader.open
reader.seek_realtime(Time.utc - 1.hour)

batch = [] of JournalEntry
batch_size = 100

while entry = reader.next_entry
  batch << entry

  if batch.size >= batch_size
    process_batch(batch)
    batch.clear
  end
end

# Process remaining entries
process_batch(batch) unless batch.empty?

Filtered Reading

reader = JournalReader.new
reader.open
reader.seek_tail

# Only process error messages
while entry = reader.next_entry
  next unless entry.priority
  next unless entry.priority.to_i <= 3 # Error level and below

  handle_error(entry)
end

Error Handling

Connection Errors

reader = JournalReader.new
unless reader.open
  Log.error { "Failed to open journal - check permissions" }
  return
end

Seek Failures

unless reader.seek_realtime(some_time)
  Log.warn { "Could not seek to #{some_time}, using tail" }
  reader.seek_tail
end

Read Errors

while entry = reader.next_entry
  begin
    process_entry(entry)
  rescue ex
    Log.error { "Failed to process entry #{entry.cursor}: #{ex.message}" }
    # Continue processing other entries
  end
end

Performance Considerations

Memory Usage

• Each JournalEntry holds field data in memory
• Large journals may require streaming processing
• Consider field filtering to reduce memory footprint

Seek Performance

• seek_head/seek_tail: O(1) - immediate positioning
• seek_cursor: O(1) - direct position lookup
• seek_realtime: O(log n) - binary search on timestamps

Read Performance

• next_entry: O(1) - sequential access
• Field access: O(1) - hash lookup
• Large field sets may impact processing speed

Optimization Tips

# Pre-allocate readers for reuse
@reader = JournalReader.new

# Use cursors for resumable processing
# Batch entries to reduce function call overhead
# Filter early to avoid processing unwanted entries

Thread Safety

JournalReader instances are not thread-safe. Each thread should use its own reader instance. Concurrent access to the same journal can be achieved by coordinating read positions between threads.

Resource Management

Always call close when finished to free system resources:

reader = JournalReader.new
begin
  reader.open
  # Use reader...
ensure
  reader.close
end

Common Issues

Permission Denied

• Ensure user has access to journal files
• Check systemd-journal group membership
• Verify journal file permissions

Empty Journal

• New systems may have minimal journal content
• Check journalctl --list-boots for available data

Cursor Invalid

• Cursors can become invalid after journal rotation
• Implement fallback to seek_tail for invalid cursors

while entry = reader.next_entry
  puts "#{entry.timestamp}: #{entry.message}"
end

# Read entries from last hour
reader.seek_realtime(Time.utc - 1.hour)