Early accessBy invitation, and the SDKs aren't published yet.Ask for an invitation
Skip to Content
Docs

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.

DoDon'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

attrspayload
ForFields to filter, break down and chart byDetail you read when you open one event
Examplesids, durations, status codes, flagsa server response, a stack trace
FilterableYes, by path and value (attr=payment.method:card)No (stored compressed)
Limits200 leaves, strings up to 1,024 bytes, string arrays up to 64 items, objects nested up to 4 levelsAny 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.