@yskomur/node-sdjournal

Native Node.js bindings for the systemd sd-journal API — read and write.

Built with pure NAPI (C), no C++ wrapper, ABI-stable across Node versions.

Features

✍️ Write	print(), send() (structured fields via sd_journal_sendv)
📖 Read	seekHead/Tail/Cursor/Time, getCursor, readEntry, readEntries
🔍 Filter	addMatch, setUnit, setIdentifier, setPriority, clearFilters
👀 Follow	reader.follow() with tail/head/current start modes
🟦 Types	Full TypeScript definitions (.d.ts)

Requirements

• Linux with systemd
• libsystemd-dev (Debian/Ubuntu) or systemd-devel (Fedora/RHEL)
• Node.js ≥ 18

Install

npm install @yskomur/node-sdjournal

Usage

Write

const { print, send, Priority } = require('@yskomur/node-sdjournal');

print(Priority.INFO, 'VM başlatıldı');

send({
  MESSAGE:           'VM started',
  PRIORITY:          String(Priority.INFO),
  SYSLOG_IDENTIFIER: 'myapp',
  VM_ID:             'vm-42',
});

Read

const { JournalReader, OpenFlags, Priority } = require('@yskomur/node-sdjournal');

const r = JournalReader.open(OpenFlags.LOCAL_ONLY);
r.setIdentifier('myapp');
r.setPriority(Priority.INFO);
r.seekTime(new Date(Date.now() - 5 * 60_000));

for (const entry of r.readEntries(50)) {
  console.log(`[${entry.timestamp.toISOString()}] ${entry.message}`);
}
r.close();

Follow (tail -f)

const ac = new AbortController();
process.on('SIGINT', () => ac.abort());

await r.follow(
  entry => console.log(entry.message, entry.cursor),
  { signal: ac.signal, start: 'tail' },
);

API

Method	Description
print(priority, message)	sd_journal_print wrapper
send(fields)	sd_journal_sendv — structured
JournalReader.open(flags?)	Journal aç
seekHead/Tail/Cursor/Time	Konumlan
getCursor()	Mevcut cursor'ı al
next() / previous()	İterate
getEntry()	Entry oku → normalized { message, priority, fields, cursor, timestamp }
readEntry() / readEntries(limit?)	High-level read helper
addMatch(str)	Filter: "FIELD=value"
setUnit / setIdentifier / setPriority	Common filter helper'ları
clearFilters()	Tüm filter'ları temizle
wait(usec?)	Yeni veri bekle
follow(fn, opts?)	`start: 'tail'

Normalized Entry Shape

getEntry(), readEntry(), and readEntries() return:

{
  message: 'VM started',
  priority: 6,
  identifier: 'myapp',
  unit: 'myapp.service',
  cursor: 's=...',
  realtimeUsec: 1710000000000000,
  timestamp: new Date(),
  fields: {
    MESSAGE: 'VM started',
    PRIORITY: '6',
    SYSLOG_IDENTIFIER: 'myapp'
  }
}

Filter Helpers

const r = JournalReader.open();
r.setUnit('nginx.service');
r.setIdentifier('myapp');
r.setPriority(Priority.ERR);

These helpers use addMatch() internally, so multiple calls are combined as journal matches. Use clearFilters() to reset them.

Follow Start Modes

• tail (default): seek to end and emit only newly appended entries
• head: seek to beginning and stream forward from the oldest available entry
• current: keep the current reader position and continue from there

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Credits

Designed and written by Claude.ai (Anthropic) in collaboration with @yskomur.

Read API ergonomics, test updates, and documentation refresh contributions by Codex.

License

MIT