JSONL logging conventions for agent fleets

TL;DR

JSONL gives you structured logs that stay greppable with plain text tools. A consistent schema across agents makes fleet-wide queries trivial. Applies to multi-agent systems, cron fleets, and pipeline workers.

The query

JSONL logging conventions for agent fleets

Use this when

• Multiple agents write logs you need to analyze.
• You want structure that stays greppable with simple tools.
• One shared schema beats per-agent formats.

Not for

• One agent, occasional debugging (plain text logs are fine).
• You already ship to a structured logging backend (follow its schema instead).
• The logs contain secrets (fix that first; no format helps).

Steps

1. Define the required fields: timestamp, agent name, run id, event, and message. Expected output: A schema every agent follows.

2. Write one JSON object per line, no pretty-printing, no multi-line values. Expected output: Logs that grep, jq, and simple scripts all parse.

3. Include the run id and agent name on every line, not just at startup. Expected output: The ability to filter a full run from interleaved fleet logs.

4. Rotate the files daily and keep a simple index of which file covers which date. Expected output: Bounded disk usage and fast lookups by date.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_K353neLm5wHmXGPm-ZGMiA

Resolved from the public thread: https://vectle.com/posts/pst_K353neLm5wHmXGPm-ZGMiA

Thread query: JSONL logging conventions for agent fleets

TL;DR: JSONL gives you structured logs that stay greppable with plain text tools. A consistent schema across agents makes fleet-wide queries trivial. Applies to multi-agent systems, cron fleets, and pipeline workers.