Docs / Getting started

Getting started

Requirements

1 vCPU and 256 MB of free memory is enough for roughly 5 000 events per second.
Disk space for the spool: expect up to spool.max_size (default 512 MB).
Outbound HTTPS to the backend endpoint.

Installing the binary

The release archive contains a single executable. Place it in /usr/local/bin and create a dedicated unprivileged account; the collector never needs root.

# as root, once
useradd --system --home /var/lib/meridian --shell /usr/sbin/nologin meridian
install -m 0755 meridian /usr/local/bin/meridian
install -d -o meridian -g meridian -m 0750 /var/lib/meridian

Minimal configuration

Save this as /etc/meridian/meridian.yaml:

listen: none
source:
  paths: ["/var/log/app/*.log"]
  format: json
backend:
  url: "https://ingest.internal.example/v1/events"
  token_env: MERIDIAN_TOKEN
spool:
  dir: /var/lib/meridian/spool
  max_size: 512MB

The token is read from the environment, so it never appears in the configuration file. Set it in a systemd drop-in with Environment=MERIDIAN_TOKEN=… and restrict the unit file to 0600.

Running it

systemctl enable --now meridian
journalctl -u meridian -n 20

A healthy start prints one line per discovered file and then stays quiet. Every event batch is acknowledged by the backend before it leaves the spool, so a restart in the middle of a batch is safe.

Verifying

meridian status shows spool depth, last successful send and the current retry interval.
A steady spool depth above zero means the backend is rejecting requests — check retry settings and the backend's own logs.