Events
One event is one thing that happened, with a stable name, a level, an area and the fields you filter by.
Everything in Lyrelog is an event. An event says what happened (message), how serious it is
(level), in which part of the app (category), to whom (user_id, session_id,
install_id), with some small fields to filter and chart by (attrs) and, when needed, a bigger
blob you only read when you open it (payload).
{
"event_id": "6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f",
"ts": "2026-11-18T10:00:00.123Z",
"level": "error",
"category": "checkout",
"message": "payment_declined",
"user_id": "user-1",
"attrs": { "code": 51, "attempt": 2, "method": "card" },
"payload": { "response": "..." }
}The message is a stable name
Write message as an event name, not as prose: payment_declined, checkout_done,
http_request_failed. Names that never change can be counted, charted, put in a funnel and
grouped into errors. Put what varies (ids, durations, codes) in attrs.
| Do | Don't |
|---|---|
payment_declined with attrs: { code: 51 } | "Payment declined with code 51 for user-1" |
The message can be up to 2,048 bytes.
Levels
From quietest to loudest: trace, debug, info (the default), notice, warning, error,
critical. The dashboard colors each one, draws errors below the axis of the explorer's chart
and groups error and critical events on the Errors page.
SDKs drop events below their minimumLevel (default debug) before queueing them.
Category: the area of the app
category (shown as Area in the dashboard) is the part of the app the event belongs to:
checkout, sync, onboarding, network. It works like OSLog's category. The dashboard
filters and counts by it. Optional, up to 64 bytes. Every SDK has a logger per area so you don't
repeat it.
Attributes and payload
attrs | payload | |
|---|---|---|
| For | Fields to filter, break down and chart by | Detail you read when you open one event |
| Examples | ids, durations, status codes, flags | a server response, a stack trace |
| Filterable | Yes, by path and value (attr=payment.method:card) | No (stored compressed) |
| Limits | 200 leaves, strings up to 1,024 bytes, string arrays up to 64 items, objects nested up to 4 levels | Any JSON up to 64 KiB once serialized |
Attribute values can be strings, numbers, booleans, null, arrays of strings and nested objects.
Names can't contain dots (nest an object instead) and can't start with _.
Log numbers as numbers (latency_ms: 412, not "412"): Insights
can then chart their average, median or p95.
The SDKs fit every event to these limits before queueing it: long strings are cut on a character
boundary and an oversized payload is replaced by
{"lyrelog_truncated": true, "bytes": N, "preview": "..."}, with the start of the payload as the
preview.
Context
Each event also carries a resource: the app id, version and build, the OS and its version, the
device model, the locale, the SDK, the environment and the
platform. The SDKs fill it in for you. The server adds the
country.
Ids and duplicates
Every event has an event_id, a UUID made once when it is logged. Delivery is at least once: if
a batch is sent twice, events with the same event_id and ts are stored once.