# Deleting your account
> What goes with your account, and what stays with the people you work with.
Source: https://docs.lyrelog.com/account/deleting
On your **Account** page, under **Delete your account**, choose **Delete account**, type your
email and, if you use two-step sign-in, a code from your authenticator app or a recovery code.
Then choose **Delete my account**. If you signed in more than 10 minutes ago, Lyrelog asks you to
sign in again first.
- Your sign-in methods, passkeys and sessions go, and you're signed out.
- Every organization where you were the only person goes too, with its projects and all their
events.
- In organizations with other people, they keep everything: the projects, the events and the plan.
- **This can't be undone.** Copies in Lyrelog's backups are gone within 30 days.
If you're the only owner of an organization that has other people, Lyrelog won't delete the
account yet: make someone else an owner first (see [Organizations](/account/organizations)),
or remove the other people.
If you can't sign in any more, write to hello@lyrelog.com from your account's address and Lyrelog
deletes it for you. Lyrelog keeps a note in its own administration log of the deletion, the
address and the reason; nothing of the account itself is left.
Deleting an account doesn't delete events your apps sent about your own users from organizations
that stay. For those, see [A person's data](/projects/privacy-requests).
# Emails from Lyrelog
> Every email Lyrelog sends you, and why.
Source: https://docs.lyrelog.com/account/emails
Lyrelog sends email from **hello@lyrelog.com**. Each email below is about your account or your
organization. The first column is its subject; words in italics are filled in.
| Email | When |
|---|---|
| You're on the Lyrelog waitlist | You asked for an invitation on [lyrelog.com](https://lyrelog.com). |
| Your invitation to Lyrelog | It's your turn. The link makes your account and your organization, and works once, for 14 days. See [Getting access](/account/getting-access). |
| Welcome to Lyrelog | Your account is made. It links to setting up your first project. |
| *Name* invited you to *organization* on Lyrelog | An owner invited you by email. The link works once, for 7 days. See [Organizations](/account/organizations). |
| *Name* joined *organization* | Someone accepted an invitation you made. |
| Confirm your email for Lyrelog | Your email isn't confirmed yet. The link works for 24 hours. |
| Your sign-in link for Lyrelog | You asked for one because you lost your passkey. It works once, for an hour. |
| A sign-in link was made for your Lyrelog account | Lyrelog's administrator made a sign-in link for you, with the reason. The email itself doesn't sign you in. |
| *Something* was added to your Lyrelog account | A new way to sign in (a passkey, or a GitHub, Google or Apple account) was added. If it wasn't you, remove it from your account page. |
| *Organization* is now on *plan* | Lyrelog changed the plan of an organization you own. See [Plans and usage](/account/plans). |
| *Organization* has used 80 % of this month's events | Sent to the owners once a month, as a heads-up. See [Plans and usage](/account/plans#emails-about-your-usage). |
| *Organization* reached this month's events | A Free organization used all its events: new ones wait in your apps (see [Plans and usage](/account/plans#at-the-free-limit)) until the month turns. |
| *Organization* passed what its plan includes | A paid organization went past what its plan includes. Nothing stops. |
If an email you expect doesn't arrive in a few minutes, look in the spam folder.
# Getting access
> Ask for an invitation, make your account with GitHub, Google or Apple, and get your organization.
Source: https://docs.lyrelog.com/account/getting-access
Lyrelog is in early access. Accounts are made from an invitation, and there is no open sign-up
yet.
## Ask for an invitation [#ask-for-an-invitation]
Ask on [lyrelog.com](https://lyrelog.com). You get an email saying you're on the waitlist. People
are invited in small groups; when it's your turn, an invitation arrives at the same address.
## Make your account [#make-your-account]
The invitation's link makes your account and an organization of your own, where your projects
and your team live.
1. Open the link. It works **once**, for **14 days**.
2. Type a name for your **Organization**: your company, your team or just you.
3. Choose **Continue with GitHub**, **Google** or **Apple**. That account is how you sign in.
Creating the account means you accept the [terms](https://lyrelog.com/terms) and the
[privacy policy](https://lyrelog.com/privacy).
Then Lyrelog helps you set up your first project and its key (see the
[Quickstart](/quickstart)), and emails you a welcome.
A used or expired invitation says so. Ask for a new one.
## Add a passkey [#add-a-passkey]
Lyrelog has no passwords. Once you're in, add a passkey from **Your account**: next time it signs
you in directly, with Face ID, Touch ID, your phone or a password manager. See
[Account security](/account/security#passkeys).
## Already have an account [#already-have-an-account]
If you're signed in when you open an invitation to Lyrelog, it makes a new organization for your
current account instead of a new account. Type its name and choose **Create the organization**.
To make an account from the invitation instead, don't sign in first.
## Joining someone's organization [#joining-someones-organization]
An invitation from someone's organization is a different link: it adds you to their
organization, not one of your own. Without an account, it makes one with GitHub, Google or
Apple. See
[Organizations](/account/organizations#joining).
# Organizations
> Who sees which projects, owners and members, invitations, and leaving.
Source: https://docs.lyrelog.com/account/organizations
Projects and people belong to an **organization**. Everyone in an organization sees all its
projects and their events, and its [plan](/account/plans) covers them all.
An account made from an [invitation to Lyrelog](/account/getting-access) comes with an
organization of its own. An account made from an organization's invitation is in that
organization only. You can be in several organizations: your own and the ones you're invited
to.
Open **Organization** from the account menu. If you're in more than one, pick which at the top
of the page. The page shows the organization's name, its people, its plan and its projects.
## Roles [#roles]
| | Owner | Member |
|---|---|---|
| See every project and its events | Yes | Yes |
| Create projects | Yes | |
| Change project settings, retention | Yes | |
| Create and revoke keys | Yes | |
| Rename the organization | Yes | |
| Invite, change roles, remove people | Yes | |
| Delete a project | Yes | |
| Save and delete saved views | Yes | Yes |
| Download a person's events | Yes | Yes |
| Delete a person's events | Yes | |
| Leave the organization | Yes | Yes |
An organization always keeps at least one owner. The only owner can't leave or become a member:
make someone else an owner first.
## Renaming it [#renaming-it]
Owners change the **Name** and choose **Save**. The name is shown to the organization's people,
in invitations and in emails.
## Inviting someone [#inviting-someone]
In **People**, choose **Invite someone as** Member or Owner. Then:
- **Type their email** and choose **Send invitation**. Lyrelog emails them the link, and also
shows it to you.
- Or leave the email empty and choose **Make a link**, and send it yourself.
Either way, the link works **once**, for **7 days**, and is shown only now. Open invitations are
listed with who made them and when they expire, and owners can **Revoke** them.
Anyone who has the link can use it, whatever address it was sent to. Send it only to the person
you mean, and **Revoke** it if it went astray. You can email up to 20 invitations an hour.
## Joining [#joining]
Opening an invitation shows the organization and your role.
- **Signed in:** choose **Join as** your email.
- **New to Lyrelog:** choose **Join with GitHub**, **Google** or **Apple**. That makes your
account and adds you. The account signs in with that provider.
- **Have an account but signed out:** choose **Sign in first**, then come back to the link.
When you join, whoever invited you gets an email. A used or expired link says so: ask for a new
one.
## Changing roles and removing people [#changing-roles-and-removing-people]
Owners change anyone's role with the role menu next to their name, and remove anyone with the
remove button. Removed people lose access to every project in the organization right away. The
read and full-access keys they made are revoked too; ingest and server keys keep working (revoke a
server key yourself if they saw it).
## Leaving [#leaving]
Anyone can leave an organization with the leave button next to their own name, except its only
owner.
# Plans and usage
> What each plan includes, how events are counted, what happens at the limit, and where to see your usage.
Source: https://docs.lyrelog.com/account/plans
A plan belongs to an **organization**, not to a person or a project. Every project in the
organization shares it, and their events count together. Every plan has every feature, and no
limit on projects or people.
## Plans [#plans]
| Plan | Price | Events |
|---|---|---|
| Free | €0 | 1,000,000 a month. Past that, new events wait until the month turns or the plan changes. |
| Pro | €19 a month | 10,000,000 included, then €1.50 per extra million. No hard stop. |
| Business | Talk to us | For over 200,000,000 events a month. |
| Unlimited | Not sold | Given by Lyrelog. No limit. |
Lyrelog takes no payments today. An organization starts on Free, unless its invitation came
with another plan. To ask about another plan, write to [hello@lyrelog.com](mailto:hello@lyrelog.com).
Lyrelog can set an organization's plan, sometimes until a date. After that date, it goes back
to Free. The plan then shows **until** that day. Each change is emailed to the organization's
owners and listed under [Done by Lyrelog](/account/security#done-by-lyrelog) on their
account page.
## How events are counted [#how-events-are-counted]
Every event the ingest accepts counts, from every project and environment in the organization.
The count runs by calendar month in UTC and starts again on the 1st.
## At the Free limit [#at-the-free-limit]
When a Free organization reaches 1,000,000 events in the month, the ingest refuses new events
with `429 Too Many Requests` and a `Retry-After` header of at most an hour, until the month turns or the plan
changes. Nothing already stored is touched.
The SDKs treat this like any other `429`: they keep the events where they were sent and retry
later, and log one warning saying the month's events are used. **How many events can wait, and
for how long, depends on the platform:**
| Where the events come from | Where they wait | How many, how long |
|---|---|---|
| Apps on Apple devices (Swift) | On disk | Up to 20 MB and 7 days; kept across launches |
| Android apps | On disk | Up to 20 MB and 7 days; kept across launches |
| React Native and Flutter apps | On disk, in the native SDK's queue | Up to 20 MB and 7 days; kept across launches |
| Browsers (JavaScript) | In memory | Up to 10,000 events or 16 MB; lost when the page closes |
| Servers: Node, Python, Go | In memory | Up to 10,000 events or 16 MB; lost when the process ends or restarts |
| Servers: the JVM | On disk, in a temporary directory | Up to 20 MB and 7 days; lost when the process ends, unless `storageDirectory` keeps them for the next start |
| Your own code over the HTTP API | Wherever you keep them | Your choice: retry after `Retry-After` |
Past those caps, the oldest events are dropped first. Events that never arrive aren't counted.
See the [HTTP API](/http-api#429-the-monthly-quota) for the response.
While a Free organization's month is used up, a banner at the top of the dashboard tells everyone
in the organization, with the date events resume.
## One address's share of the day [#one-addresss-share-of-the-day]
With the public ingest key, one address may send at most a fiftieth of the plan's month in a UTC
day (Free 20,000 events, Pro 200,000, Business 4,000,000; Unlimited has no such limit), so a key
copied out of an app can't spend the organization's month from one machine. Servers should send
with a server key, which isn't limited this way, and events your Apple app proves with App
Attest, or your Android app with Key Attestation, don't count either. Past it, that address gets
`429` until the next UTC day; other addresses keep sending. See
[Verified events](/concepts/verification#the-daily-share-of-one-address).
## Emails about your usage [#emails-about-your-usage]
Each organization's owners get an email when it has used 80 % of what its plan includes in a
month, and another at 100 %. On Free, the second one says that new events aren't stored
until the month turns, and wait where they were sent. One of each per month at most.
## How long events are kept [#how-long-events-are-kept]
Each plan keeps events for up to a number of days (Free 7, Pro 30, Business a year). See
[Retention](/concepts/retention#retention-and-your-plan).
## Where to see it [#where-to-see-it]
**Plan and usage**, in the account menu, shows each organization you're in:
- its plan, and whether you own it or are a member,
- this month's events against what the plan allows (the limit on Free, what's included on a
paid plan),
- events per day this month,
- events per project.
The plan and this month's events also show in each project's
[settings](/projects/settings), on the [organization page](/account/organizations)
and on your [account page](/account/security).
## Terms [#terms]
Plans are covered by the [terms](https://lyrelog.com/terms). How Lyrelog handles your data and
your users' data is in the [privacy policy](https://lyrelog.com/privacy) and the
[data processing agreement](https://lyrelog.com/dpa).
# Account security
> GitHub, Google and Apple, passkeys, sign-in links, two-step sign-in, recovery codes and what Lyrelog did for your account.
Source: https://docs.lyrelog.com/account/security
Open **Your account** from the account menu. It holds your name, every way you sign in, your
organizations' plans and what Lyrelog's administrator did concerning you.
## Ways to sign in [#ways-to-sign-in]
Lyrelog has no passwords.
| Method | Notes |
|---|---|
| GitHub, Google, Apple | Your account is made with one of them, from an [invitation](/account/getting-access). More can be linked under **Linked accounts**. |
| Passkeys | Added from your account page once you're in. Face ID, Touch ID, your phone or a password manager. There's no password to type or leak. |
You can have several at once, and it's worth it: a passkey, or a second passkey on another
device, is a way in if you lose access to the first. Lyrelog won't let you remove your only way
to sign in.
Signing in with GitHub, Google or Apple whose verified email matches your account's confirmed
email links that provider to your account (after your two-step code, if you use one).
You stay signed in on a browser for up to 30 days, and you're signed out after 14 days without
using the dashboard. **Where you're signed in** lists your browsers and the computers where the
command-line tool is signed in, and signs any of them out. The command-line tool's sign-ins and
**Access tokens** for CI have their own expiries: see [Sign in](/cli/login#the-session).
## Passkeys [#passkeys]
**Add a passkey**, give it a name, and confirm on your device. From then on, the sign-in page's
passkey button signs you in directly. A passkey is two steps already, so it never asks for a
code. Remove one with its remove button.
## Lost your passkey? [#lost-your-passkey]
On the sign-in page, choose **Lost your passkey? Get a sign-in link by email** and type your
account's email. The link signs you in once and works for an hour; then add a new passkey. It
still asks for your two-step code if you have one.
If you can't get the email, write to [hello@lyrelog.com](mailto:hello@lyrelog.com). Lyrelog's
administrator can make you a one-time sign-in link that works for 24 hours. You're emailed when
that happens, and it is listed under [Done by Lyrelog](#done-by-lyrelog).
## Linked accounts [#linked-accounts]
Link GitHub, Google or Apple to sign in with them. Each provider account can be linked to one
person only. Unlink one when you no longer use it.
## Two-step sign-in [#two-step-sign-in]
After GitHub, Google or Apple, or a sign-in link, ask for a code from an authenticator app.
1. Turn it on and scan the code with your authenticator app (1Password, Google Authenticator,
Authy and others). If you can't scan it, type the key shown.
2. Type a code from the app to prove it works.
3. **Save your recovery codes**: Lyrelog shows 10, once.
Turning it off, or making new recovery codes, needs a current code.
## Recovery codes [#recovery-codes]
If you lose your phone, each recovery code lets you in once, in place of the app's code: choose
**Use a recovery code** at sign-in. Your account page shows how many are left. **Make new codes**
replaces them all.
## Confirm your email [#confirm-your-email]
If your account page asks you to **Confirm your email**, open the link Lyrelog sent you, or
choose **Send the link again**. The link works for 24 hours. Until your email is confirmed, a
sign-in link can't reach you there if you lose your passkey.
## The recent sign-in rule [#the-recent-sign-in-rule]
Some changes need a **recent sign-in: within the last 10 minutes**: adding or removing a
passkey, linking or unlinking GitHub, Google or Apple, turning two-step sign-in on or off, making a
**Send events from a server**, **Read events** or **Full access** key, making an access token or
making one last longer, keeping a command-line sign-in longer than a browser's, deleting a project,
and deleting your account. Otherwise
Lyrelog asks you to **Sign in again** first. Turning two-step sign-in off, and making new recovery
codes, also need a current code. Changes to how you sign in end your other sessions.
When a passkey or a provider is added to your account, Lyrelog emails you. If it wasn't you,
remove it from your account page: that also signs you out everywhere else.
## Done by Lyrelog [#done-by-lyrelog]
This section lists what Lyrelog's administrator did concerning your account or the
organizations you own, newest first, with when and the reason given:
- **A sign-in link was made for your account.** You're also emailed about it.
- **An organization's plan was set** to another plan. Its owners are also emailed. See
[Plans and usage](/account/plans).
It says **Nothing so far** when there is nothing to list.
# Use with AI agents
> Give Claude Code, Cursor or any coding agent these docs, and a prompt that adds Lyrelog to your project.
Source: https://docs.lyrelog.com/ai-agents
Every page here is also plain Markdown, so a coding agent can read the docs instead of guessing
from memory, which for a new service like Lyrelog it gets wrong.
## Files for agents [#files-for-agents]
| Address | What it holds |
|---|---|
| [`/llms.txt`](https://docs.lyrelog.com/llms.txt) | An index of every page with its description, each linking to its Markdown. The [llms.txt](https://llmstxt.org) format agents look for. |
| [`/llms-full.txt`](https://docs.lyrelog.com/llms-full.txt) | Every page in one file, to put the whole docs in an agent's context at once. |
| `/.md` | One page, e.g. [`/sdks/go.md`](https://docs.lyrelog.com/sdks/go.md). |
Each page also has **Copy Markdown**, and **Open** to send it to ChatGPT, Claude or Cursor, under
its title.
## A prompt to add Lyrelog to your project [#a-prompt-to-add-lyrelog-to-your-project]
Paste it into your agent, with your ingest key in place of `lyr_ing_...` (the project's
**API keys** page, see [Keys](/concepts/keys); it only writes, so it's safe to ship in an app). Keep the key out of the repository if you
prefer: put it in an environment variable and tell the agent its name.
```text
Add Lyrelog logging to this project. Read https://docs.lyrelog.com/llms.txt first, then the
page of the SDK for this project's language (or the HTTP API page if there's no SDK for it).
Don't rely on what you remember about Lyrelog: follow the docs.
1. Install the SDK and start it once, where the app or service starts, with the ingest key
lyr_ing_... (or from the environment variable LYRELOG_KEY). Keep the default endpoint.
2. Make sure queued events are sent before the process ends: flush or close the client as the
SDK page says for this kind of program (server, CLI, serverless function, app).
3. Capture errors: unhandled ones the way the SDK page shows, and the places in this code that
catch an error and carry on.
4. Log a few events where something happens to a person: sign in, a payment, a sync, a failed
request. Use a stable snake_case name as the message (payment_declined), a level, an area
(category) and attributes with the details to filter by.
5. Identify the person with our own user id (setUser or the SDK's equivalent), never an email
address, and clear it on sign-out.
6. Never put passwords, tokens, keys, cookies, full request bodies or personal data in messages,
attributes or payloads.
7. Tell me which environment the events will arrive under, so I can pick it in the dashboard.
```
The SDKs aren't published yet, so an agent can't install them today: the prompt works once
they are. Until then it can send events over the [HTTP API](/http-api).
## Let an agent read your events [#let-an-agent-read-your-events]
The [command-line tool](/cli) lets a coding agent search events, read errors and follow a
person through a session, signed in as you. It writes JSON when an agent runs it. You sign in
once with `lyrelog login`; the agent can't sign in by itself. See
[For agents and scripts](/cli/agents), with a prompt to investigate an error.
## Tips [#tips]
- **Name the page.** "Read https://docs.lyrelog.com/sdks/python.md and add Lyrelog to the
FastAPI app" is faster and more accurate than a search.
- **Ask for a test event.** Have the agent log one event when the app starts, run it, and check
it arrives (see [Quickstart](/quickstart)): it's the quickest way to catch a wrong key or
environment.
- **Review what it logs.** Agents tend to log too much. One event per thing that happened, with
a stable name, is easier to search, chart and pay for than a line per function call.
# For agents and scripts
> When the CLI writes JSON, what the JSON looks like, its exit codes, and a prompt for a coding agent to investigate an error.
Source: https://docs.lyrelog.com/cli/agents
The command-line tool is made to be run by programs as much as by people. Under a coding
agent, in CI or in a pipe, it writes JSON and nothing else: no colours, no spinner, no
questions. A coding agent can then search events, read errors and follow a person through a
session as easily as you can in the dashboard.
## JSON or tables [#json-or-tables]
Each run decides once, in this order:
1. `--human` writes tables, even into a pipe. `--json` writes JSON, even at a terminal. They
can't go together.
2. Otherwise it writes JSON when stdout isn't a terminal (`lyrelog errors | jq`,
`> file.json`), or when one of the variables below is set.
3. Otherwise, at a terminal, it writes tables.
Agents often run commands in a pseudo-terminal, so the terminal check alone isn't enough.
These variables count:
| Variable | Set by |
|---|---|
| `LYRELOG_AGENT` | You: set it to any value to force agent mode anywhere |
| `AI_AGENT` | The cross-tool convention: Claude Code sets it, Vercel's `@vercel/detect-agent` reads it |
| `AGENT` | Amp (`AGENT=amp`), Goose (`AGENT=goose`); also `1` or `true`. Any other value is ignored: the name is too common |
| `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT` | Claude Code, in every shell it runs |
| `CURSOR_AGENT`, or `CURSOR_EXTENSION_HOST_ROLE=agent-exec` | Cursor's agent (CLI and editor) |
| `CODEX_SANDBOX`, `CODEX_SANDBOX_NETWORK_DISABLED`, `CODEX_CI`, `CODEX_THREAD_ID` | OpenAI Codex CLI |
| `GEMINI_CLI` | Gemini CLI's shell tool |
| `OPENCODE=1`, `OPENCODE_CLIENT` | opencode |
| `AMP_CURRENT_THREAD_ID` | Amp |
| `AUGMENT_AGENT`, `ANTIGRAVITY_AGENT` | Augment, Antigravity |
| `CI` | GitHub Actions, GitLab CI, CircleCI, Buildkite and most others. `CI=false` or `CI=0` doesn't count. |
Some are left out on purpose. `CURSOR_TRACE_ID` and `REPL_ID` are set in every Cursor terminal
and Replit shell, including a person's. aider runs commands without a terminal, so the pipe
check catches it anyway.
Colours appear only in tables at a terminal. `NO_COLOR` (any value), `TERM=dumb` and
`--no-color` turn them off. An agent or CI is never asked a question, even with `--human`.
## The JSON contract [#the-json-contract]
- **stdout carries only the data.** A list is a JSON array of the server's own objects, with
the dashboard API's field names unchanged. One thing is an object.
- **Indented at a terminal** (with `--json`), **one line otherwise.**
- **`--follow` writes one JSON object a line** (NDJSON), one per event, until it's stopped.
- **When a list was cut**, by `--limit` or by pages, stderr gets one line saying how to get
the rest. Pass `next` as flags to the same command:
```json
{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."}
{"more":true,"next":"--page 1"}
```
- **A failure writes one line to stderr** and exits with a [code](#exit-codes):
```json
{"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}
```
`error` and `hint` are for people. `code` is stable, for programs. `status` is the HTTP
status, when the server answered. `retry_after` is in seconds, when the server asked to wait.
- **Something that can't be undone needs `--yes`**: revoking a key, deleting a person's data,
removing someone from an organization, deleting a saved view. Nobody can answer a question,
so without `--yes` it stops with exit code 2.
```bash
lyrelog events --level error --since 7d -n 1
```
```json
[{"event_id":"adea33e4-26eb-422e-b904-96649c0e7830","ts":1795167007485,"level":"error","category":"sync","message":"cloud_save_failed","user_id":"pl-fe0958c6","install_id":"76f5a7d0-81b0-4c36-8908-eefd6c936abf","session_id":"51e19a18-ca3e-4428-a10b-baeadc7eaaf8","app_id":"com.example.tilefall","app_version":"1.6.3","app_build":"202609301304","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,2","locale":"fr_FR","country":"FR","environment":"production","platform":"ios","received_at":1795167047509,"verified_by":"","attrs":{"reason":"schema_mismatch","record":"progress","status":422}}]
```
and on stderr:
```json
{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}
```
Times are Unix milliseconds. Some more:
```bash
lyrelog errors | jq -c '.[0] | {name, area, count, players, versions, sample_event}'
lyrelog events values message --level error --since 7d | jq -c '.[0:2]'
lyrelog events -f --level error | jq -r '.message'
lyrelog keys create --type server --name tilefall-api | jq -r .secret
```
```json
{"name":"cloud_save_failed","area":"sync","count":823,"players":124,"versions":["1.6.3"],"sample_event":"adea33e4-26eb-422e-b904-96649c0e7830"}
[{"value":"cloud_save_failed","count":823,"players":124},{"value":"daily_upload_failed","count":178,"players":124}]
```
Field names are the API's, so a count of people is `players` whatever the project calls them.
## Exit codes [#exit-codes]
They're stable: scripts and agents can branch on them.
| Code | `code` | Meaning |
|---|---|---|
| 0 | | Done |
| 1 | `error` | Something else failed (the server, a file) |
| 2 | `usage` | A wrong command, flag or value; or `--yes` is needed |
| 3 | `not_signed_in` | Not signed in, or the session ended: `lyrelog login` |
| 4 | `reauth_required` | The action needs a sign-in from the last 10 minutes: `lyrelog login`, then retry |
| 5 | `forbidden` | Signed in, but not allowed (an owner's action) |
| 5 | `browser_only` | Only the dashboard does this: deleting the account or a project, changing how you sign in. The error names the page. Also an access token trying to make or change tokens |
| 6 | `not_found` | No such project, event, key or person (or not yours) |
| 7 | `refused` | The server refused the request as it is (a 400 or 409, say) |
| 8 | `rate_limited` | Too many requests, or the server is busy: wait `retry_after` |
| 9 | `network` | The server couldn't be reached |
| 130 | `interrupted` | Ctrl-C |
Stopping `--follow` with Ctrl-C ends it normally, with 0.
## Signing in [#signing-in]
An agent can't sign in by itself. `lyrelog login` refuses to run under an agent or CI:
```json
{"error":"An agent (claude-code) can't sign in by itself: signing in needs a person","hint":"Ask a person to run `lyrelog login` in a terminal on this computer; the CLI then uses that sign-in. In CI, set LYRELOG_TOKEN to an access token from your account page: https://docs.lyrelog.com/cli/login#scripts-and-ci","code":"not_signed_in"}
```
A person runs `lyrelog login` once, in a terminal on that computer, and every agent there
uses that sign-in until it ends (see [Sign in](/cli/login#the-session)). The agent acts
as that person, with their projects and their role. Creating a server, read or admin key also
needs that person to have signed in within the last 10 minutes.
In CI, or for an agent with no person around, use an access token: a person makes one with
`lyrelog tokens create` right after `lyrelog login`, or on the account page, and sets it as
`LYRELOG_TOKEN` (see [Scripts and CI](/cli/login#scripts-and-ci)).
## A prompt to investigate an error [#a-prompt-to-investigate-an-error]
Paste this into Claude Code, Cursor or another coding agent, in the repository of the app,
after you've run `lyrelog login` and `lyrelog use ` in a terminal there. Put the
error's name in place of `cloud_save_failed`.
```text
Investigate the error "cloud_save_failed" in our app with the Lyrelog CLI (lyrelog),
which is installed and signed in. It writes JSON when you run it. Run `lyrelog --help` and
the commands' --help first; don't guess flags. Read only: don't create, change, revoke or
delete anything.
1. `lyrelog errors --since 7d` and find this error: how many times, how many people, which
versions, when it started, and its sample_event and sample_session.
2. `lyrelog events get `: read its attributes and payload.
3. `lyrelog events --session --oldest-first`: what happened before it in
that session.
4. Compare: `lyrelog events values version --message cloud_save_failed --since 7d`,
and the same with device, then `lyrelog insights rate --hits cloud_save_failed
--of "" --by version`.
5. Look at one or two more people it reached (`lyrelog person `), to check the
pattern holds.
6. Find the code that logs this event in this repository, explain the most likely cause from
what the events show, and propose a fix. Say what's proven by the events and what's a
guess.
If a command fails with code reauth_required or not_signed_in, stop and tell me: I'll sign in
again. Don't paste customers' event content anywhere outside this conversation.
```
Agents also read these docs as Markdown: see [Use with AI agents](/ai-agents).
# api and open
> lyrelog api calls any dashboard API route with your sign-in; lyrelog open goes to the same page in the dashboard.
Source: https://docs.lyrelog.com/cli/api
## `api` [#api]
`lyrelog api` calls any route of the dashboard's API with your sign-in, like `gh api`. It's for
anything the other commands don't wrap yet.
```bash
lyrelog api
```
- The method is `GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
- The path may leave out `/api`: `projects/{project}` is `/api/projects/{project}`. Give the
path only. The server comes from `--url` or `LYRELOG_URL`.
- `{project}` becomes the current project's id (the default one, or `-p`).
```bash
lyrelog api GET /api/me
```
```json
{"admin":false,"organizations":[{"id":4,"name":"Alex Rivera","role":"owner","plan":"free","plan_until":null}],"user":{"id":10,"email":"alex@example.com","name":"Alex Rivera"}}
```
```bash
lyrelog api GET projects/{project}/regions -F from=1763500000000
lyrelog api PATCH projects/{project} --data '{"retention_days":30}'
lyrelog api POST projects/{project}/views --data @view.json
```
| Flag | What |
|---|---|
| `-F`, `--field` | `key=value`. On a `GET` it's a query parameter; on `POST`, `PUT` and `PATCH` it's a field of the JSON body (numbers, `true`, `false` and `null` are sent as such). Repeat it for more. |
| `-d`, `--data` | The request body as it is: JSON, `@file` to read a file, or `@-` for stdin. Not with `-F`. |
The answer is printed as it comes. At a terminal, JSON is indented and coloured. An answer
with no body prints its status (`{"status":204}` in JSON mode). A failure exits with the same
[exit codes](/cli/agents#exit-codes) as every command, with the error as JSON on stderr
in JSON mode.
These are the routes the dashboard itself uses, and they aren't documented here. For a
documented API to read events from scripts, use the [Read API](/read-api).
## `open` [#open]
`lyrelog open` opens a page of the dashboard in your browser, on the current project.
```bash
lyrelog open errors
lyrelog open person gc-2e427d7b
lyrelog open settings --print
```
```text
https://app.lyrelog.com/p/e8bc11c6e22f/settings
```
| Page | What |
|---|---|
| (none) | The explorer |
| `events` | The explorer |
| `errors` | The Errors page |
| `sessions` | Sessions |
| `people` | The project's people |
| `insights` | Insights |
| `releases` | Releases |
| `keys` | API keys |
| `settings` | Project settings |
| `projects` | All projects |
| `usage` | Usage and plan |
| `account` | Your account |
| `organization` | Your organization |
| `person ` | One person's page |
| `event ` | The explorer, searching for one event |
| Flag | What |
|---|---|
| `--print` | Print the address instead of opening it |
Over SSH, or when no browser can be opened, it prints the address. In JSON mode, for an
agent or a script, it doesn't open anything: it prints `{"url":"..."}`.
# Events
> lyrelog events searches with the explorer's filters, follows new events live, and shows one event in full.
Source: https://docs.lyrelog.com/cli/events
`lyrelog events` is the [explorer](/dashboard/explorer) in a terminal. It lists a
project's events, newest first, from the last 24 hours unless you say otherwise. It also
answers to `lyrelog logs` and `lyrelog log`.
```bash
lyrelog events --level warning+ --since 7d
```
```text
Tilefall · production · last 7 days
10:30:07 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
10:27:43 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
10:24:48 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
10:22:05 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
10:17:06 ▌error chat_socket_gave_up chat attempts=4 match_id=0d9acb1f-503f-4818-a5a1-19336d1f0d8a
Showing 5 events. For more: --cursor MTc5NTE2NjIyNjExMTo3...
```
The first line names the project, the environment and the time window. Each event is one line:
its time, its level, its name (message), its area (category) and its attributes. Events from
other days show the date too.
## Filters [#filters]
The filters are the explorer's, and they take what its address takes: `"a|b"` for any of
several values, `"!a"` for anything but that one. Quote them, because `|` and `!` mean
something to the shell.
| Flag | Filters by |
|---|---|
| `--level` | Levels: `error`, `error,critical`, or `warning+` for warning and worse. Levels are `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`. |
| `--message` | The event name (message), exactly |
| `-q`, `--query` | Search the message, area and attributes |
| `--category` | Area (category): `checkout`, `"a\|b"` or `"!a"` |
| `--attr` | An attribute, `path:value`, or `path!:value` for not. Repeat it for more. |
| `--user` | One person's id (the `user_id` the app sends) |
| `--session` | One session's id |
| `--install` | One install's id |
| `--version` | App version: `2.4.0`, or `"2.4.0\|2.4.1"` |
| `--platform` | Platform: `ios`, `android`, `web`, `python`... |
| `--device` | Device model |
| `--os` | OS version |
| `--country` | Country code: `ES`, or `"ES\|PT"` |
| `--locale` | Locale: `es_ES` |
| `--verified` | How the sender was proven: `server`, `app_attest`, `none`. `"!none"` keeps only [verified](/concepts/verification) events. |
| `--env` | Environment. The default is the project's default, as in the dashboard; `all` searches every one. |
```bash
lyrelog events --attr board.size:9 --attr result!:win
lyrelog events --level error --version "2.4.0|2.4.1" --platform '!web'
lyrelog events --user pl-fe0958c6 --since 7d --limit 500
lyrelog events --verified '!none'
lyrelog events --env all -q "card declined"
```
The default environment is the project's, so events sent under `development` don't appear
unless you pass `--env development` or `--env all` (see
[Environments](/concepts/environments)).
## Time [#time]
| Flag | What |
|---|---|
| `--since` | A window ending now: `15m`, `1h`, `6h`, `24h`, `7d`, `30d`, or any number of `s`, `m`, `h`, `d` or `w`. Default `24h`. |
| `--from` | The start |
| `--to` | The end. Default now. |
| `--oldest-first` | Oldest first, from the start of the window |
`--from` and `--to` take:
- RFC 3339: `2026-11-19T10:00:00Z`
- a date and time in your computer's time zone: `2026-11-19 10:00`
- a date: `2026-11-19`, which means midnight at its start, in your time zone
- Unix milliseconds (`1763550000000`) or seconds
- how long ago: `2h`, `3d`
`--since` can't go with `--from` or `--to`. With only `--from`, the window ends now; with only
`--to`, it starts 24 hours before.
```bash
lyrelog events --from 3d --to 2d
lyrelog events --from 2026-11-15 --to 2026-11-16 --oldest-first
```
```text
Tilefall · production · Nov 15 00:00 to Nov 16 00:00
Nov 15 00:00:00 ▌info leaderboard_submit_confirmed leaderboards board=tilefall.daily.pure latency_ms=420
Nov 15 00:00:11 ▌info game_started game board.seed=4052403362615 board.size=7 m…
Nov 15 00:00:17 ▌info match_round_won multiplayer match_id=b60cc0cc-b294-46a3-9186-35c71a…
```
## How many, and the rest [#how-many-and-the-rest]
| Flag | What |
|---|---|
| `-n`, `--limit` | How many events at most. Default 100. Pages of up to 1,000 are fetched as needed. |
| `--cursor` | Carry on from where a previous list stopped |
When there are more events than `--limit`, the last line gives the `--cursor` to pass for the
next ones. Run the same command again with that flag added, keeping the same filters. In JSON
mode, the cursor goes to stderr as `{"more":true,"next":"--cursor ..."}` (see
[The JSON contract](/cli/agents#the-json-contract)).
## Follow new events [#follow-new-events]
`-f` (`--follow`) prints the latest events from the last hour (up to `--limit`, oldest first),
then each new one as it arrives, until you press Ctrl-C. It asks every 4 seconds, as the
dashboard's live mode does, for what Lyrelog received since the last time. New events are
printed in the order they arrived, so a batch a phone sends late, after being offline, shows
when it arrives, with its own (older) times, as long as those are within the last 2 days.
```bash
lyrelog events -f
```
```text
Tilefall · production · following, Ctrl-C to stop
10:41:52 ▌info app_launch app cold_start_ms=612 launch_reason=icon
```
`lyrelog events -f --level error` follows only errors.
The filters work as usual. `--since`, `--from` and `--to` don't, because it shows what
arrives from now on. In JSON mode it writes one JSON object a line (NDJSON); each has
`received_at`, when Lyrelog received it (Unix ms), next to its own `ts`. If the server
can't be reached for a while, it says so on stderr and keeps trying. It stops if the session
ends or the project is gone.
## `events get` [#events-get]
One event in full: who, where, the app, the device, its attributes and its payload.
```bash
lyrelog events get adea33e4-26eb-422e-b904-96649c0e7830
```
```text
▌ cloud_save_failed error
sync
Time 2026-11-20 10:30:07.485 CET 8m ago
Event adea33e4-26eb-422e-b904-96649c0e7830
Player pl-fe0958c6
Session 51e19a18-ca3e-4428-a10b-baeadc7eaaf8
Install 76f5a7d0-81b0-4c36-8908-eefd6c936abf
App com.example.tilefall 1.6.3 (202609301304)
Device iPhone18,2 iOS 27.2.0
Locale fr_FR
Country FR
Environment production
Platform ios
Attributes
{
"reason": "schema_mismatch",
"record": "progress",
"status": 422
}
Payload
{
"description": "The server refused the save",
"detail": "field 'mode' is not allowed in format 3; expected format 4"
}
```
The tool finds the event by its id among everything the project keeps (its whole retention).
Pass `--ts` with the event's time in Unix milliseconds (the `ts` field of the JSON) to go
straight to it, skipping that lookup.
| Flag | What |
|---|---|
| `--ts` | The event's time in Unix milliseconds (skips the lookup) |
## `events summary` [#events-summary]
The totals (events, people, sessions, errors) and the most frequent values of each field, as
the explorer's side panel shows them. It takes the same filters and time flags as `events`.
```bash
lyrelog events summary --since 7d
```
```text
Tilefall · production · last 7 days
52,886 events 300 players 3,202 sessions 1,127 errors
category game 11.6k leaderboards 10k app 7,110 daily 5,362 campaign 5,126 account 3,304
level info 36.7k debug 13.7k error 1,110 warning 1,074 notice 292 critical 17
version 2.0 30.4k 1.6.3 22.5k
...
```
## `events values` [#events-values]
The most frequent values of one field, or of an attribute (`attr.`), within the
filters: what the explorer's filter menu offers. Fields include `level`, `category`,
`message`, `version`, `device`, `country`, `environment`, `platform` and `verified`.
```bash
lyrelog events values message --level error --since 7d
```
```text
Tilefall · production · last 7 days
Message Events Players
cloud_save_failed 823 124
daily_upload_failed 178 124
match_update_denied 43 38
leaderboard_submit_failed 29 17
chat_socket_gave_up 28 28
purchase_failed 9 8
```
```bash
lyrelog events values attr.board.size
```
| Flag | What |
|---|---|
| `--search` | Only values containing this |
It also takes the filters and time flags of `events`.
## `events attributes` [#events-attributes]
The attribute paths events carry, most common first. Also `lyrelog events attrs`.
```bash
lyrelog events attributes --of game_won --numeric
```
```text
Attribute Events
hints_used 360
seconds 360
```
| Flag | What |
|---|---|
| `--of` | Only in these events (messages): `"a\|b"` |
| `--numeric` | Only attributes with numbers, the ones [`insights trend --metric value`](/cli/investigate#insights) can chart |
It also takes the filters and time flags of `events`.
# Command-line tool
> Lyrelog from your terminal. Search and follow events, read errors, sessions and people, manage projects, keys and organizations.
Source: https://docs.lyrelog.com/cli
`lyrelog` is the dashboard in a terminal. It searches events with the explorer's filters,
follows them live, and shows errors, sessions, people, releases, insights and usage. It also
manages projects, keys, organizations and your account. Deleting your account or a project, and
changing how you sign in (passkeys, linked accounts, two-step), stay in the dashboard: Lyrelog
refuses them from the CLI, so a copied CLI session can't lock you out or erase your data.
It's made for two kinds of user. A person gets tables and colours. A program or a coding
agent gets JSON and nothing else. The tool notices which one is running it (see
[How output switches](#how-output-switches)).
Like the [SDKs](/sdks), the command-line tool isn't published during early access.
Until it is, the `go install` below fails: the repository is private and has no release
yet.
## Install [#install]
You need Go 1.26 or later:
```bash
go install go.lyrelog.com/cli/cmd/lyrelog@latest
```
This puts `lyrelog` in `$(go env GOPATH)/bin`, so make sure that folder is on your `PATH`. No
prebuilt binaries are published yet; Homebrew (`brew install GonzaloFuentes28/tap/lyrelog`)
comes with the first release.
## First steps [#first-steps]
### Sign in [#sign-in]
```bash
lyrelog login
```
Your browser opens the dashboard. Approve this computer, and the terminal picks up the
sign-in. There's another way over SSH; see [Sign in](/cli/login).
### Choose a project [#choose-a-project]
```bash
lyrelog projects
lyrelog use tilefall # its slug, its name or its id
```
```text
Project Slug Events People Errors Last event 24 hours
● Tilefall tilefall 7,291 205 187 7m ago ▂▄▃▅▃▄▅▆▆▇██▆▃▁▂▁▁▁▁▂▃▅▂
```
Commands use this project unless you pass `-p `. If you can only see one project,
`lyrelog login` picks it for you.
### Look at events [#look-at-events]
```bash
lyrelog events --level error --since 7d
```
```text
Tilefall · production · last 7 days
10:30:07 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
10:27:43 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
10:24:48 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
```
Next, try `lyrelog errors` for problems grouped, worst first. Or `lyrelog events -f` to watch
events as they arrive.
## What it does [#what-it-does]
| Look at your data | |
|---|---|
| [`events`](/cli/events) | Search events as the explorer does; `-f` follows new ones. `events get`, `summary`, `values`, `attributes` |
| [`errors`](/cli/investigate#errors) | Problems grouped by area and event name, worst first |
| [`sessions`](/cli/investigate#sessions) | Sessions: who, how long, what happened, errors |
| [`people`](/cli/investigate#people) | The project's people, in its own word |
| [`person`](/cli/investigate#person) | One person: totals, recent sessions and events; export or delete their data |
| [`releases`](/cli/investigate#releases) | Each app version's health |
| [`insights`](/cli/investigate#insights) | Trends, rates and funnels |
| [`usage`](/cli/investigate#usage) | This month's events against your plan |
| Set things up and more | |
|---|---|
| [`projects`, `use`](/cli/setup#projects) | List, show, change and make projects, and choose the default one |
| [`keys`](/cli/setup#keys) | List, create and revoke API keys |
| [`orgs`](/cli/setup#organizations) | Organizations, their people and invitations |
| [`account`](/cli/setup#account) | Your name, and where you're signed in |
| [`tokens`](/cli/setup#access-tokens) | Access tokens for CI: list, create, change the expiry, revoke |
| [`login`, `logout`, `whoami`](/cli/login) | Sign in and out |
| [`open`](/cli/api#open) | Open the same page in the dashboard |
| [`api`](/cli/api#api) | Call any dashboard API route, signed in |
Every command has `--help`, with examples.
## How output switches [#how-output-switches]
At a terminal, `lyrelog` draws tables with Lyrelog's colours. It writes JSON instead when:
- its output goes into a pipe or a file (`lyrelog errors | jq`), or
- a coding agent or CI runs it (Claude Code, Cursor, Codex and others, detected by the
environment variables they set).
`--json` and `--human` force either one. In JSON mode, stdout carries only the data, errors
are one JSON line on stderr, and the exit code says what went wrong. See
[For agents and scripts](/cli/agents).
Colours adapt to light and dark terminals. Set `LYRELOG_THEME=dark` or `light` if the guess is
wrong. `NO_COLOR=1` or `--no-color` turns them off.
# Errors, sessions and people
> The dashboard's Errors, Sessions, People, Releases, Insights and Usage pages, as commands.
Source: https://docs.lyrelog.com/cli/investigate
These commands show what the dashboard's pages show. Except for `usage`, each one works on
one project and takes the filters and time flags of [`lyrelog events`](/cli/events#filters):
`--level`, `--attr`, `--version`, `--platform`, `--env`, `--since`, `--from`, `--to` and the
rest. Their window is the **last 7 days** unless you say otherwise.
The examples use a project whose people are called players. The tool uses each project's own
word (see [Project settings](/projects/settings)).
## Errors [#errors]
`lyrelog errors` (or `lyrelog issues`) is the [Errors page](/dashboard/errors): error and
critical events grouped by area and event name, worst first. Each row shows how many times it
happened, the change against the window before, how many people it reached, when it was last
seen, the versions it happened on and how it trends.
```bash
lyrelog errors
```
```text
Tilefall · production · last 7 days
Event Area Count Change Players Last seen Versions Trend
● cloud_save_failed sync 823 new 124 7m ago 1.6.3 ▄▇▁▄▇▂▅▇▁▃▇▂▄▇▂▄▇▁▄█▂▁
● daily_upload_failed daily 178 new 124 32m ago 2.0, 1.6.3 ▄▄ ▃▅ ▃▇▂▃█▂▄▇▁▄▄▂▂▅▂▂
● match_update_denied multiplayer 43 new 38 38m ago 2.0, 1.6.3 ▂▇ ▄▅ ▂▂ █▂▄▅█▂▄▇ ▅▇ ▂
● chat_socket_gave_up chat 28 new 28 20m ago 2.0, 1.6.3 ▃▃ ▆█▃ █ ▆▆ ▆▆▃▃▃ ▃█ ▆
● leaderboard_submit_fa… leaderboards 29 new 17 1d ago 2.0, 1.6.3 █
● database_open_failed app 17 new 16 26m ago 2.0, 1.6.3 ▃▃▆▃ ▃ ▃▃ ▃▃▆▃ █ ▃
● purchase_failed purchases 9 new 8 12h ago 2.0, 1.6.3 ▄ █ █ ▄ ▄▄ ▄
```
| Flag | What |
|---|---|
| `--warnings` | Count warnings too |
```bash
lyrelog errors --since 24h --warnings
lyrelog errors --version 2.4.1 --json | jq '.[0]'
```
In JSON, each problem carries a `sample_event`, `sample_user` and `sample_session`, ready for
[`lyrelog events get`](/cli/events#events-get), `lyrelog person` and
`lyrelog events --session`.
## Sessions [#sessions]
`lyrelog sessions` is the [Sessions page](/dashboard/sessions): who, how long, how many
events and errors, the device and version, and the first and last event (with the first
error, if any).
```bash
lyrelog sessions --with-event purchase_failed --sort longest
```
```text
Tilefall · production · last 7 days
Started Player Length Events Errors Device Version From → to Session
3d ago pl-3860c35c 37m 21s 34 1 iPad14,1 2.0 app_launch → app_background ✗ purchase_fai… cfc2523d-c1a3-4b4f-b576-53d98d2826e1
12h ago pl-6405980a 28m 15s 24 1 iPhone17,1 1.6.3 app_launch → app_background ✗ purchase_fai… e567122a-70f9-42de-9f5b-f088684aa0a2
1d ago pl-dcb099d1 23m 23s 25 1 iPhone18,1 2.0 app_launch → app_background ✗ purchase_fai… c8c02c07-0f64-4d20-9575-835f2758432f
```
| Flag | What |
|---|---|
| `--errors` | Only sessions with errors |
| `--with-event` | Only sessions with this event (message) in them |
| `--min-duration` | Only sessions at least this long: `30s`, `5m` |
| `--sort` | `recent` (default), `longest`, `errors` or `events` |
| `--page` | The page, 50 sessions a page, counting from 0 |
To read one session's events in order, pass its id (the `sid` field in JSON) to
`lyrelog events --session --oldest-first`.
## People [#people]
`lyrelog people` is the [People page](/dashboard/people): who used the app in the window,
with their events, sessions, errors, and latest device and version. It also answers to
`lyrelog users` and `lyrelog players`.
```bash
lyrelog people --sort errors
```
```text
Tilefall · production · last 7 days
Player Events Sessions Errors Last seen First seen Device Version OS Country
pl-4e5d999b 553 30 24 1h ago 6d ago iPhone18,2 1.6.3 iOS 27.0.3 ES
pl-eb2cd82f 455 27 24 7h ago 6d ago iPad16,6 1.6.3 iOS 27.2.0 IT
pl-519465f0 443 27 20 11h ago 6d ago iPad14,1 1.6.3 iOS 27.0.3 FR
50 of 300 players. Next: --page 1
```
| Flag | What |
|---|---|
| `--search` | Ids starting with this |
| `--sort` | `last_seen` (default), `events`, `errors`, `sessions` or `first_seen` |
| `--page` | The page, 50 people a page, counting from 0 |
## Person [#person]
`lyrelog person ` (or `user`, `player`) is one person's page: how many events they
have, their recent sessions and their latest events. The id is the `user_id` the app sends,
matched exactly.
```bash
lyrelog person pl-fe0958c6 -n 4
```
```text
Player pl-fe0958c6 in Tilefall
290 events in all, first 6d ago, last 8m ago
Sessions last 7 days
Started Length Events Errors Device Version From → to Session
8m ago 40s 5 1 iPhone18,2 1.6.3 app_launch → app_background ✗ cloud_save_failed 51e19a18-ca3e-4428-a10b-baeadc7eaaf8
2h ago 23m 58s 23 1 iPhone18,2 1.6.3 app_launch → app_background ✗ cloud_save_failed 2f396cf7-4741-4102-acba-abe64fe9b31e
12h ago 20m 38s 19 0 iPhone18,2 1.6.3 app_launch → app_background 5e9f9fee-7158-4ed1-87eb-46c6585d658e
Latest events
10:30:36 ▌info app_background app seconds_open=11
10:30:07 ▌error cloud_save_failed sync reason=schema_mismatch record=progress status=422
10:29:58 ▌info sign_in_completed account latency_ms=641 method=apple
10:29:57 ▌debug api_request network latency_ms=187 path=/app-version status=200
Everything of theirs: lyrelog events --user pl-fe0958c6 --since 7d
```
| Flag | What |
|---|---|
| `-n`, `--limit` | How many recent events to show. Default 20. |
| `--since`, `--from`, `--to` | The window for sessions and events. Default `7d`. |
| `--env`, `--platform` | As in `events` |
| `--export ` | Write all their events as JSON lines to this file, `-` for stdout |
| `--delete` | Delete all their events (owners only; can't be undone) |
| `-y`, `--yes` | With `--delete`: don't ask to confirm |
### Privacy requests [#privacy-requests]
These are the dashboard's **A person's data** tools (see
[Privacy requests](/projects/privacy-requests)):
```bash
lyrelog person pl-fe0958c6 --export pl-fe0958c6.ndjson # an access request (any member)
lyrelog person pl-fe0958c6 --export - | jq .message
lyrelog person pl-fe0958c6 --delete # an erasure request (owners)
```
`--delete` asks you to type the person's id to confirm. In JSON mode nobody can answer, so it
needs `--yes`.
## Releases [#releases]
`lyrelog releases` (or `lyrelog versions`) is the [Releases page](/dashboard/releases):
each app version's people, sessions, the share of sessions without errors, errors and
critical events, and when it was first and last seen.
```bash
lyrelog releases
```
```text
Tilefall · production · last 7 days
Version Players Sessions Without errors Errors Critical First seen Last seen
2.0 171 1,849 90% 194 13 6d ago 10m ago
1.6.3 129 1,353 36% 933 4 6d ago 7m ago
```
## Insights [#insights]
`lyrelog insights` is the [Insights page](/dashboard/insights): how often something
happens (`trend`), how often it fails (`rate`), and how far people get through a flow
(`funnel`).
### `insights trend` [#insights-trend]
How often one or more events happen over time, optionally broken down.
```bash
lyrelog insights trend game_won --by version
```
```text
Tilefall · production · last 7 days
Event Group Events Over time
game_won 2.0 1,552 ████▇▇▆▂
game_won 1.6.3 1,098 ▇██████▂
```
```bash
lyrelog insights trend game_won --metric users --since 30d
lyrelog insights trend game_won --metric value --value-path seconds --stat p90
```
| Flag | What |
|---|---|
| `--by` | Break down by `version`, `country` or `attr:` |
| `--metric` | `events` (default), `users` (people), or `value` (a number attribute) |
| `--value-path` | With `--metric value`: the attribute holding the number |
| `--stat` | With `--metric value`: `avg`, `p50`, `p90`, `p95`, `p99` or `max` |
`lyrelog events attributes --numeric` lists the attributes that hold numbers.
### `insights rate` [#insights-rate]
The share of one set of events over another: failures over attempts.
```bash
lyrelog insights rate --hits purchase_failed --of "purchase_started|purchase_failed"
```
```text
Tilefall · production · last 7 days
Event Rate Hits / tries Over time
purchase_failed of purchase_started, purchase_failed 10.59% 9 / 85 ▁▅██▅▇▅▁
```
| Flag | What |
|---|---|
| `--hits` | The events counted (failures): `"a\|b"` |
| `--of` | The events they're out of (attempts): `"c\|d"` |
| `--by` | Break down by `version`, `country` or `attr:` |
### `insights funnel` [#insights-funnel]
How many people reach each step of a flow, in order, and how long each step takes. Give two or
more events.
```bash
lyrelog insights funnel app_launch game_started game_won --window 1h
```
```text
Tilefall · production · last 7 days · within 1h
Step Players Of the first Median time
1. app_launch ████████████████████ 300 100%
2. game_started ███████████████████░ 291 97% 6m 56s
3. game_won ███████████████████░ 288 96% 5m 57s
```
| Flag | What |
|---|---|
| `--window` | Time allowed from the first step to the last. Default `1d`. |
### Saved views [#saved-views]
`lyrelog insights views` lists the project's saved views.
`lyrelog insights delete-view ` deletes one; it asks first, and needs `--yes` in JSON
mode.
## Usage [#usage]
`lyrelog usage` shows this month's events against your plan, for each organization you belong
to, and how they split across its projects (see [Plans and usage](/account/plans)).
```bash
lyrelog usage
```
```text
Alex Rivera · Free plan
██░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 5.3%
52,925 of 1,000,000 events a month · counts start again on Dec 1
█ per day
Project Events Share
Tilefall 52,925 100%
```
| Flag | What |
|---|---|
| `--org` | One organization, by id or name. Default: all of yours. |
# Sign in
> lyrelog login approves this computer in the browser. Over SSH, paste a code instead. The session lasts like a browser's.
Source: https://docs.lyrelog.com/cli/login
The command-line tool has no password and no key of its own. You approve it from the
dashboard, where you're already signed in. That gives this computer a session, just like a
browser's.
## `lyrelog login` [#lyrelog-login]
```bash
lyrelog login
```
1. Your browser opens `app.lyrelog.com/cli/authorize`. The page shows this computer's name
and the account it will act as, and lists what the tool can and can't do.
2. Choose **Approve**. The browser hands the sign-in back to the terminal on this computer,
and the page says **You're signed in**. You can close the tab.
3. The terminal says who you're signed in as. If you can only see one project, it becomes the
default; if you can see more, run `lyrelog use `.
```text
Approve MacBook-Pro in the browser window that opened.
If none did, open:
https://app.lyrelog.com/cli/authorize?...
On another computer? Press Enter to get a code to paste instead.
```
Only approve a sign-in you started yourself. **Cancel** on the page leaves the tool signed
out. If the browser doesn't come back within 5 minutes, the terminal asks for a code instead.
The sign-in uses OAuth's authorization code with PKCE, as Claude Code does. The browser can
only send it back to an address on this computer (`127.0.0.1`), and only the terminal that
started it can use it.
### Over SSH, or without a browser [#over-ssh-or-without-a-browser]
On a server you reach over SSH, or on Linux without a display, `lyrelog login` doesn't try to
open a browser. Neither does `lyrelog login --no-browser`. Instead, it prints the page's
address:
```text
Open this page, approve server-1, and paste the code it shows:
https://app.lyrelog.com/cli/authorize?...
Paste the code:
```
Open that address in any browser, choose **Approve**, and copy the code the page shows into
the terminal. The code works once, for the next 5 minutes, and only for the terminal that
asked. Never paste it anywhere else, or give it to someone: with it, they could sign in as
you.
The tool also skips the browser when `BROWSER=none` is set. When it does open one, it uses
`$BROWSER` if that's set.
`lyrelog login` refuses to run under a coding agent, in CI, or without a terminal to type
in. A person signs in once, in a terminal on that computer, and the agent uses that sign-in.
See [For agents and scripts](/cli/agents#signing-in).
## The session [#the-session]
A CLI session is the same kind of session as a browser's:
- It ends after **14 days unused**, and after **30 days** at most, unless you [keep it](#keep-a-sign-in-longer). `lyrelog whoami` shows when
it ends at the latest. After that, the next command asks you to run `lyrelog login`.
- Creating a **server, read or admin key** needs a
[recent sign-in](/account/security#the-recent-sign-in-rule): within 10 minutes of
approving. If it's been longer, the command stops with "This needs a recent sign-in" (exit
code 4). Run `lyrelog login` again, then retry.
- A CLI session can't approve another one. Approving always happens in the browser.
The session is saved in the tool's [settings file](/cli/reference#settings-file). The
tool never prints it.
### Keep a sign-in longer [#keep-a-sign-in-longer]
On your own computer you may not want to sign in again every month. Ask to keep the sign-in:
```bash
lyrelog login --keep 90d # or 30d, 1y, never
```
The approval page shows your choice and lets you change it before you approve: **Like a
browser** (the default), **30 days**, **90 days**, **1 year** or **Never expires**. A kept
sign-in lasts that long whether you use it or not, and ends sooner only if you sign it out.
Keeping one needs you to have signed in to the dashboard in the last 10 minutes; if you haven't,
the page asks you to sign in first.
A sign-in that never expires works for anyone who copies this computer's settings file, until
you sign it out. Choose it only on a computer you trust. The account page marks it **Never
expires**, and `lyrelog whoami` says so too.
### See and end your sessions [#see-and-end-your-sessions]
The account page's **Where you're signed in** lists your browsers and every computer where
the CLI is signed in, as **CLI on** and the computer's name. You can sign any of them out
there. Its next command then asks to run `lyrelog login` again.
From the terminal:
```bash
lyrelog account sessions
```
```text
ID Where Kind Signed in Last used Ends
11 MacBook-Pro command line 3m ago 15s ago this one
9 Chrome on macOS browser 4h ago 3m ago
10 build-box command line 25m ago 25m ago kept to Feb 17, 2027
```
**Ends** shows when a [kept](#keep-a-sign-in-longer) sign-in ends, or `kept, never ends`. The
others end after 14 days unused. Access tokens aren't in this list: `lyrelog tokens` shows them.
```bash
lyrelog account sign-out 10 # the ID from the list
```
## `lyrelog logout` [#lyrelog-logout]
```bash
lyrelog logout
```
This ends the session on the server, so the token stops working everywhere, and removes it
from this computer's settings.
## `lyrelog whoami` [#lyrelog-whoami]
Who you're signed in as, on which server, when the session ends, the default project and your
organizations. `lyrelog status` is the same command.
```text
✓ Signed in as Alex Rivera
Server app.lyrelog.com
Session ends by Dec 19, 22:10 at the latest (14 days unused ends it sooner, unless you kept it)
Project Tilefall e8bc11c6e22f
Organizations Alex Rivera · owner · Free
```
## Environment variables [#environment-variables]
| Variable | What |
|---|---|
| `LYRELOG_TOKEN` | An access token (`lyr_tok_...`, from `lyrelog tokens create` or your account page) or a CLI session token. It wins over the saved sign-in. |
| `LYRELOG_URL` | The dashboard's address. Default `https://app.lyrelog.com`. `--url` wins over it. |
Each server has its own sign-in in the settings file, so `lyrelog login --url `
signs in to another one without affecting the first. The last server you signed in to
becomes the default.
### Scripts and CI [#scripts-and-ci]
Use an **access token** (`lyr_tok_...`). Make one from the terminal, right after signing in
(it needs a sign-in from the last 10 minutes):
```bash
lyrelog login
lyrelog tokens create --name "GitHub Actions, deploy" # --expires 30d, 90d (default), 1y or never
```
Or in the dashboard: open your account page, **Access tokens**. You need to have signed in in
the last 10 minutes there too. Either way:
1. Name it after what will use it ("GitHub Actions, deploy") and pick when it expires: 30 days,
90 days (the default), a year, or never.
2. Copy it: it's shown once. Put it in your CI's secrets as `LYRELOG_TOKEN`, never in a repository.
`lyrelog tokens` lists them, and [Access tokens](/cli/setup#access-tokens) has the other
commands.
```bash
# GitHub Actions
env:
LYRELOG_TOKEN: ${{ secrets.LYRELOG_TOKEN }}
run: lyrelog errors --since 24h --json
```
A token acts as you, like the CLI after `lyrelog login`, with two differences: it doesn't end when
unused, only when it expires or you revoke it (on the account page or with `lyrelog tokens
revoke`), and it counts as a recent
sign-in only in its first 10 minutes, so it can't create server, read or admin keys after that.
Like a CLI session, it can't delete the account or a project, or change how you sign in, and it
can't make another token.
A token that never expires works for anyone who gets hold of it until you revoke it. The account
page marks such tokens **Never expires**, and `lyrelog tokens` shows `⚠ never`. Prefer an
expiry, and revoke tokens you don't use.
You can change a token's expiry later, counted from now, on the account page or with
`lyrelog tokens expiry --expires 30d` (or `90d`, `1y`, `never`). Sooner works any time;
later, or never, needs a sign-in from the last 10 minutes.
Only reading events from a script? The [Read API](/read-api) with a read key
(`lyr_read_...`) also works, and it's limited to one project.
# Reference
> The command-line tool's global flags, environment variables, settings file, shell completion and version.
Source: https://docs.lyrelog.com/cli/reference
## Global flags [#global-flags]
Every command takes these.
| Flag | What |
|---|---|
| `-p`, `--project` | The project: its id, slug or name. Default: the one chosen with `lyrelog use`. |
| `--url` | The dashboard's address. Default `https://app.lyrelog.com`, or `LYRELOG_URL`. |
| `--json` | Write JSON, even at a terminal |
| `--human` | Write tables and colours, even into a pipe |
| `--no-color` | No colours (also `NO_COLOR=1`) |
| `-h`, `--help` | Help for the command, with examples |
## Environment variables [#environment-variables]
| Variable | What |
|---|---|
| `LYRELOG_TOKEN` | An access token (`lyr_tok_...`, from `lyrelog tokens create` or your account page) or a CLI session token. It wins over the saved sign-in. See [Scripts and CI](/cli/login#scripts-and-ci). |
| `LYRELOG_URL` | The dashboard's address. `--url` wins over it. |
| `LYRELOG_CONFIG_DIR` | The folder for the settings file |
| `LYRELOG_THEME` | `dark` or `light`, when the terminal's background is guessed wrong |
| `LYRELOG_AGENT` | Any value: write JSON, as for a coding agent |
| `NO_COLOR` | Any value: no colours |
| `BROWSER` | The browser `lyrelog login` and `lyrelog open` use; `none` for no browser |
The tool also reads the variables coding agents and CI set, to decide between JSON and tables.
See [JSON or tables](/cli/agents#json-or-tables).
## Settings file [#settings-file]
The tool keeps its settings in one JSON file, `config.json`, in:
| | Folder |
|---|---|
| macOS and Linux | `~/.config/lyrelog`, or `$XDG_CONFIG_HOME/lyrelog` when that's set |
| Windows | `%AppData%\lyrelog` |
| Anywhere | `LYRELOG_CONFIG_DIR`, when set |
The file can only be read by you (mode 0600, in a 0700 folder), and it's written in one
step, so it's never left half-written. It holds:
| Field | What |
|---|---|
| `url` | The server used when neither `--url` nor `LYRELOG_URL` says otherwise: the last one you signed in to |
| `hosts` | One entry per server, keyed by its address |
| `hosts.*.token` | The session. The tool never prints it. |
| `hosts.*.expires_at` | When the session ends at the latest (Unix seconds) |
| `hosts.*.user_email`, `hosts.*.user_name` | Who it belongs to |
| `hosts.*.project`, `hosts.*.project_name` | The default project's id, and its name for messages |
```json
{
"url": "https://app.lyrelog.com",
"hosts": {
"https://app.lyrelog.com": {
"token": "…",
"expires_at": 1797714620,
"user_email": "alex@example.com",
"user_name": "Alex Rivera",
"project": "e8bc11c6e22f",
"project_name": "Tilefall"
}
}
}
```
The token is a session like a browser's cookie: anyone who copies it acts as you until it
ends. `lyrelog logout` ends it on the server and removes it from the file.
## Exit codes [#exit-codes]
0 is done; anything else names what went wrong (2 a wrong flag, 3 not signed in, 4 a recent
sign-in needed, 6 not found...). The full table is in
[For agents and scripts](/cli/agents#exit-codes).
## Shell completion [#shell-completion]
`lyrelog completion` prints a completion script for `bash`, `zsh`, `fish` or `powershell`.
Each one's `--help` says where to put it. For zsh:
```bash
source <(lyrelog completion zsh) # this shell only
lyrelog completion zsh > "$(brew --prefix)/share/zsh/site-functions/_lyrelog" # macOS, every shell
lyrelog completion zsh > "${fpath[1]}/_lyrelog" # Linux, every shell
```
Completion needs `autoload -U compinit; compinit` in your `~/.zshrc`. Start a new shell
afterwards.
## Version [#version]
```bash
lyrelog version
```
```text
lyrelog v0.1.0 (4678ef1, built 2026-11-19, go1.27.4, darwin/arm64)
```
It shows the version (from the release, or the one `go install` fetched), the commit and the
build date when the build knows them, and the Go version and system it was built for. A build
with no version says `dev`. In JSON: `{"version","commit","date","go","os","arch"}`.
# Projects, keys and organizations
> Choose a project, change its settings, make and revoke keys, invite people and see your account, from the terminal.
Source: https://docs.lyrelog.com/cli/setup
Changing settings, keys and people works as it does in the dashboard, with the same rules.
Owners do what only owners can do. Creating a server, read or admin key needs a
[recent sign-in](/cli/login#the-session). Anything that can't be undone asks first.
Deleting a project or your account, and changing how you sign in, happen only in the dashboard
(see [Deleting a project](/projects/deleting) and [Deleting your account](/account/deleting)).
Lyrelog refuses them from the CLI, even through `lyrelog api`, with `403` and `"browser_only": true`.
## Projects [#projects]
`lyrelog projects` lists the projects you can see, with their events, people and errors in the
last 24 hours, as the dashboard's project switcher does.
```text
Project Slug Events People Errors Last event 24 hours
● Tilefall tilefall 5,593 177 103 50m ago █▆▂▂▁▂▂▂▁▆▇▇▇▆▇█▆██▁ ▁▁
```
Any command takes `-p` (`--project`) with a project's slug, its name or its id (the 12
characters in the dashboard's address).
### `use` [#use]
Chooses the project commands use when `-p` isn't given. It's saved for this server in the
[settings file](/cli/reference#settings-file).
```bash
lyrelog use tilefall
lyrelog use e8bc11c6e22f
lyrelog use # show the current one
lyrelog use --clear # forget it
```
### `projects show` [#projects-show]
A project's settings. Pass a project, or it shows the default one.
```bash
lyrelog projects show
```
```text
Tilefall e8bc11c6e22f
Slug tilefall
Your role owner
Keeps events for 7 days (your plan keeps up to 7)
Opens on production
Platforms ios
Its people are player / players
App Attest App IDs ABCDE12345.com.example.tilefall
Verified events everything is accepted
Created Nov 19, 2026
```
### `projects set` [#projects-set]
Changes a project's settings, as its [settings page](/projects/settings) does. Owners
only. Only the flags you pass change. A list replaces what's there, and `""` empties it.
```bash
lyrelog projects set --retention-days 30 --default-env production
lyrelog projects set --people player,players
lyrelog projects set --require-verified ios,android
lyrelog projects set --attest-app-ids ABCDE12345.com.example.tilefall
```
| Flag | What |
|---|---|
| `--name` | The project's name |
| `--retention-days` | Keep events this many days, up to what the plan keeps (see [Retention](/concepts/retention)) |
| `--default-env` | The environment the dashboard opens on (`all` for every one) |
| `--people` | What the project calls its people, `singular,plural`: `player,players` |
| `--platform` | What it mainly is: `ios`, `android`, `web`, `api` or `other` |
| `--platforms` | What it's made of: `ios`, `android`, `macos`, `web`, `api`, comma separated |
| `--require-verified` | Platforms it accepts only [verified](/concepts/verification) events from; `""` accepts everything |
| `--attest-app-ids` | App IDs its apps attest as with Apple App Attest (`TEAMID.bundle.id`); `""` turns it off |
### `projects create` [#projects-create]
Makes a project in one of your organizations. Organization owners only. It prints the
project's first ingest key once: put it in your app.
```bash
lyrelog projects create --name "Tilefall web" --slug tilefall-web
```
| Flag | What |
|---|---|
| `--name` | The project's name |
| `--slug` | A short name for URLs: lowercase letters, digits and dashes |
| `--org` | The organization, by id or name. Default: your only one, or the default project's. |
### `projects platform` [#projects-platform]
Adds or removes one of the [platforms](/concepts/platforms) a project is made of, with
its details. Owners only.
```bash
lyrelog projects platform add web --url https://tilefall.example
lyrelog projects platform add android --package com.example.tilefall
lyrelog projects platform add api --runtime python
lyrelog projects platform remove web
```
| Flag | What |
|---|---|
| `--url` | `web`: the website's address |
| `--package` | `android`: the Google Play package |
| `--runtime` | `api`: the server's language |
The platforms are `ios`, `android`, `macos`, `web` and `api`.
## Keys [#keys]
`lyrelog keys` (or `keys list`) lists the project's API keys, revoked ones included. The
types are those of [Keys](/concepts/keys):
| Type | Starts with | What it is |
|---|---|---|
| `ingest` | `lyr_ing_` | Public and write-only: it ships in your app |
| `server` | `lyr_srv_` | Secret: sends verified events from your servers |
| `read` | `lyr_read_` | Secret: reads every event of the project |
| `admin` | `lyr_adm_` | Secret: reads and manages the project through the API (**Full access** in the dashboard) |
```text
ID Name Type Starts with Created Last used Status
0d5c55e6-d922-4cd2-af90-3fff4e8709b7 tilefall-ser… server lyr_srv_7GLL… 51m ago 51m ago active
d3c65585-ab3f-427f-abee-13893f96c53a tilefall-ing… ingest lyr_ing_ptD_… 1h ago 1h ago active
9c81961c-3b29-47ac-b580-50c444f40372 x read lyr_read_Dg7… 3m ago never revoked 2m ago
```
### `keys create` [#keys-create]
Makes a key. Owners only. Its secret is printed once, because only a hash of it is kept.
```bash
lyrelog keys create --type ingest --name "iOS app"
lyrelog keys create --type server --name tilefall-api --json | jq -r .secret
```
| Flag | What |
|---|---|
| `--type` | `ingest` (default), `server`, `read` or `admin` |
| `--name` | Where the key is used |
A `server`, `read` or `admin` key needs a sign-in from the last 10 minutes. If yours is older,
the command stops with "This needs a recent sign-in". Run `lyrelog login`, then create the key.
A project has at most 20 active keys.
### `keys revoke` [#keys-revoke]
```bash
lyrelog keys revoke 9c81961c-3b29-47ac-b580-50c444f40372
```
Revokes a key. Owners only. Whatever uses it stops working. It asks first; `-y` (`--yes`)
skips the question, and JSON mode needs it.
## Organizations [#organizations]
`lyrelog orgs` lists your [organizations](/account/organizations), your role in each
and its plan. `lyrelog orgs show` lists one's people and open invitations.
```bash
lyrelog orgs show
```
```text
Alex Rivera 4 · Free plan · you're owner
Name Email Role Since Last sign-in
Alex Rivera alex@example.com owner Nov 19, 2026 3m ago
```
The commands below are for owners. Each takes `--org` with an id or a name. Without it, they
use your only organization, or the default project's.
| Command | What |
|---|---|
| `orgs rename ` | Rename the organization |
| `orgs invite` | Make an invitation link (7 days, works once). `--role owner` or `member` (default); `--email` emails it. |
| `orgs revoke-invite ` | Cancel an open invitation |
| `orgs role ` | Change someone's role. The member is their email or user id. |
| `orgs remove ` | Remove someone. Anyone can remove themselves, to leave. Asks first; `--yes` skips it. |
```bash
lyrelog orgs invite --role member --email ana@example.com
lyrelog orgs role ana@example.com owner
```
An invitation's link is printed once. Anyone holding it can join the organization with that
role. An organization always keeps an owner, so a change that would leave it without one is
refused.
## Account [#account]
`lyrelog account` shows your account as the account page does: your email, passkeys and
two-step sign-in.
```text
Alex Rivera alex@example.com
Email ✓ confirmed
Passkeys none
Two-step off
```
| Command | What |
|---|---|
| `account set --name ` | Change your name |
| `account sessions` | Where you're signed in: browsers and computers with the CLI (not access tokens) |
| `account sign-out ` | Sign one of those sessions out |
Adding passkeys or sign-in methods and turning on two-step sign-in happen in the browser
(`lyrelog open account`). See [Sign in](/cli/login#see-and-end-your-sessions) for
sessions.
## Access tokens [#access-tokens]
An access token (`lyr_tok_...`) lets CI or a script use the CLI or the API as you, through
`LYRELOG_TOKEN` (see [Scripts and CI](/cli/login#scripts-and-ci)). The account page's
**Access tokens** does the same as these commands.
`lyrelog tokens` (or `tokens list`) lists yours:
```text
Name ID Expires Last used
GitHub Actions, deploy 45 Feb 3, 2027 1h ago
nightly export 46 ⚠ never Oct 1
```
| Command | What |
|---|---|
| `tokens create --name ` | Make a token. `--expires 30d`, `90d` (default), `1y` or `never`. It's printed once. |
| `tokens expiry --expires ` | Change when it expires, counted from now: `30d`, `90d`, `1y` or `never` |
| `tokens revoke ` | Revoke it. Whatever uses it stops working. Asks first; `-y` (`--yes`) skips it. |
```bash
lyrelog login
lyrelog tokens create --name "GitHub Actions, deploy"
```
```text
✓ Made the access token GitHub Actions, deploy, it expires Feb 17, 2027
Token:
lyr_tok_…
Copy it now: Lyrelog shows it only once. It's a secret: store it in your CI's secrets as LYRELOG_TOKEN.
```
Making a token, and making one last longer or never expire, need a sign-in from the last 10
minutes: right after `lyrelog login`. Otherwise the command stops with "This needs a recent
sign-in" (exit 4). Making one shorter works any time. An access token can't make or change
tokens, so these commands refuse to run with `LYRELOG_TOKEN` set to one (exit 5,
`browser_only`).
A token that never expires gets a warning, and in JSON mode `--expires never` needs `--yes`.
In JSON mode, `tokens create` prints `{"token","session","never_expires"}`:
```bash
lyrelog tokens create --name ci --expires 90d --json | jq -r .token
```
# Countries
> Lyrelog works out the country from the address a batch came from, at ingest, and never stores the address.
Source: https://docs.lyrelog.com/concepts/countries
When a batch arrives at `https://ingest.lyrelog.com`, the server looks up the sender's IP
address in a local copy of DB-IP's free country database and stores only the ISO country code on
each event of the batch (`country`). The address itself is never kept, and no third-party service
is called.
A client can't set `country`: sending it is rejected as an unknown field.
Events your backend sends (Node, Python, Go) carry the country of your server, not of the person.
The same goes for events relayed through a proxy of your own: only Lyrelog's own front server is
trusted for `X-Forwarded-For`. Send events from the device when the country matters.
## Where a person is [#where-a-person-is]
The dashboard places a person by the country of their events, and falls back to the region of
their device's locale (`es_ES` is Spain) for events without one. The map on the
[explorer](/dashboard/explorer#where-people-are), the people list, the sessions list and
the **Country** filter and breakdown all use that rule.
The map credits "IP geolocation by DB-IP" (CC BY 4.0).
# Environments
> Debug builds, TestFlight and the App Store send to the same project, and each event says which.
Source: https://docs.lyrelog.com/concepts/environments
Every event carries an `environment`, so one project can hold development, beta and production
events without mixing them up. The dashboard shows one environment at a time, or all of them.
## The names [#the-names]
Each SDK names the environment its own way (below). Any other name works when you set it
yourself: lowercase letters, digits, `-` and `_`, up to 32 characters, starting with a letter or
a digit (`staging`, `internal`, `staging-eu`).
## How each SDK detects it [#how-each-sdk-detects-it]
| SDK | Detection |
|---|---|
| Swift | `development` for a Debug build or any build on the simulator, `testflight` for a build installed from TestFlight, `production` otherwise (the App Store) |
| Android | `development` when the app is debuggable (every debug build), `production` otherwise |
| React Native, Flutter | The native SDK's: Swift's rule on iOS, Android's on Android |
| JavaScript, browser | `development` on `localhost`, `127.0.0.1`, `[::1]` or a `*.localhost` host, `production` anywhere else |
| JavaScript, Node | `production` when `NODE_ENV=production`, `development` otherwise |
| Python, Go, JVM | The `LYRELOG_ENVIRONMENT` environment variable, else `production` |
## Overriding it [#overriding-it]
Set `environment` in the SDK's configuration. In Swift, `nil` keeps the detection (`null` on
Android and in Flutter, `undefined` in React Native), so you can combine it with your own rule:
```swift
Lyrelog.start(Configuration(
endpoint: URL(string: "https://ingest.lyrelog.com")!,
apiKey: "lyr_ing_...",
environment: isInternalTester ? "internal" : nil // nil = detected
))
```
`Lyrelog.detectedEnvironment` returns what the Swift SDK would pick on its own.
A build you run from Xcode, any build on the simulator, an Android debug build (also from React
Native or `flutter run`), and a web page on `localhost` all send `development`. The dashboard opens on `production`, so pick **development** (or **All
environments**) in the top bar to see your first events.
The TestFlight check reads the build's App Store receipt: a TestFlight build has a sandbox
receipt. A Release build you install yourself (ad hoc, or straight from Xcode with the Release
configuration) has none, so it counts as `production`. Set `environment` yourself when that
matters.
Over [HTTP](/http-api), set `resource.environment`. An event sent without one is stored
as `production`.
## In the dashboard [#in-the-dashboard]
The picker in the top bar lists the environments seen in the last 30 days, with how many events
each, plus **All environments**. Your choice is remembered per project in your browser. Until
you pick one, the dashboard opens on the project's default environment: `production` unless an
owner changes it in [Settings](/projects/settings), where it can also be **All**. Every page
about events follows the picker. See
[Environments and platforms](/dashboard/environments-and-platforms).
The **Environments** section of Settings also shows how the environment is decided for the
platforms the project has.
# Events
> One event is one thing that happened, with a stable name, a level, an area and the fields you filter by.
Source: https://docs.lyrelog.com/concepts/events
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`).
```json
{
"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 [#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 [#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](/dashboard/errors) page.
SDKs drop events below their `minimumLevel` (default `debug`) before queueing them.
## Category: the area of the app [#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 [#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](/dashboard/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 [#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](/concepts/environments) and the
[platform](/concepts/platforms). The SDKs fill it in for you. The server adds the
[country](/concepts/countries).
## Ids and duplicates [#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.
# Keys
> Ingest keys only write and are public by design; server, read and admin keys stay on a server.
Source: https://docs.lyrelog.com/concepts/keys
A key belongs to one project and has one of four scopes. Its prefix says which.
| Scope | Prefix | Dashboard name | What it can do | Where it lives |
|---|---|---|---|---|
| Ingest | `lyr_ing_` | Send events | Append events, nothing else | Inside your app or your web page |
| Server | `lyr_srv_` | Send events from a server | Append events, nothing else. Its events are [verified](/concepts/verification). | Your backend only. Keep it secret. |
| Read | `lyr_read_` | Read events | Query events | A server or a script. Keep it secret. |
| Admin | `lyr_adm_` | Full access | Send events and query them, for administration jobs | A server. Keep it secret. |
A read key queries its project's events through the [read API](/read-api): from a script,
a notebook or an agent on a server. It reads everything the project holds, so it never goes in
an app or a web page.
A server key sends events from your backend: from the Node, Python, Go or JVM SDK, or with `curl`.
It can't read, like an ingest key, but it is a secret: the events it sends are marked
[verified](/concepts/verification), because only your servers hold it, and one address
isn't limited to a daily share of the month with it. It never goes in an app or a web page. Apps
and web pages use the ingest key.
## Why an ingest key can be public [#why-an-ingest-key-can-be-public]
An ingest key ships inside your app binary or your web page, so assume anyone can read it. That is
fine because it can only append events to its project: it can't read, change or delete anything.
The project an event lands in always comes from the key, never from the event. To limit abuse,
each project is rate-limited (60,000 events a minute by default), and a batch over the limit gets `429`.
One address may also send only a [daily share](/concepts/verification#the-daily-share-of-one-address)
of the organization's month with it.
The flip side: anyone holding the ingest key can send events like your app's, so they aren't
[verified](/concepts/verification), unless they come from your Apple app and Apple proves it
with [App Attest](/concepts/verification#apple-apps-app-attest), or from your Android app and
the phone proves it with [Key Attestation](/concepts/verification#android-apps-key-attestation).
Those events don't count toward the daily share either.
## Keys are shown once [#keys-are-shown-once]
Lyrelog stores only a SHA-256 hash of each key. You see the key once, when you create it: copy it
then. Lost keys can't be recovered; make a new one.
## Creating and revoking [#creating-and-revoking]
Keys live on the project's **API keys** page: Settings, then **API keys**, or ⌘
K and **API keys**. Only owners can create and revoke them.
- A project has at most 20 active keys. Revoke one to make another.
- Keys don't expire: a key works until it's revoked, or until its project is deleted.
- Making a **Send events from a server**, **Read events** or **Full access** key needs a recent
sign-in (within 10 minutes). **Send events** keys don't.
- When someone leaves an organization or is removed, the read and full-access keys they made are
revoked. Ingest keys stay, because apps already out there send with them. Server keys stay
too, because your servers send with them: if the person who left saw one, revoke it and
replace it.
- Everyone in the organization sees the list of keys and when each was last used.
A revoked key stops working at once; allow up to a minute. An SDK that gets `401` or `403` stops sending until
the app restarts, and keeps its queued events.
# Platforms
> One project can hold an app, its website and its backend, and the dashboard can show each on its own.
Source: https://docs.lyrelog.com/concepts/platforms
A project can hear from several parts of a product: a game's iOS app, its website and its API
can all send to one project. One person (by `user_id`) can then be followed across them, and the
dashboard can still show one part at a time.
There are two sides to this: the `platform` field on each event, and the list of platforms you
set up on the project.
## The platform on each event [#the-platform-on-each-event]
Every event carries a `platform`: which part of the product sent it. The SDKs send:
| SDK | Platform |
|---|---|
| Swift | The OS: `ios`, `macos`, `tvos` or `visionos`; `apple` on watchOS |
| Android | `android` |
| React Native, Flutter | The OS, from the native SDK underneath: `ios` or `android` |
| JavaScript | `web` in a browser, `node` on Node |
| Python | `python` |
| Go | `go` |
| JVM (Java and Kotlin) | `jvm` |
Override it in the configuration when a name says more, for example `platform: "api"` for your
backend and `platform: "worker"` for a queue consumer. The naming rule is the same as for
environments: lowercase letters, digits, `-` and `_`, up to 32.
When an event arrives without a platform, the server derives one from the SDK name and the OS
(`lyrelog-swift` on iOS is `ios`, `lyrelog-js` with `os_name: "web"` is `web`), else from the OS
name itself.
## The project's platforms [#the-projects-platforms]
In [Settings](/projects/settings), the **Platforms** section lists what sends events to the
project, one card each with what it is:
| Platform | What you tell Lyrelog | What Lyrelog does with it |
|---|---|---|
| iOS app, Mac app | Its App Store listing: search by name or paste its link | Shows the app's name, developer, rating, version and bundle id |
| Android app | Its Google Play package (`com.example.app`) or Play link | Finds the app's name and icon on Google Play |
| Website | Its address (`example.com`) | Finds the site's icon |
| Server | Its language: Node, Python, Go, Java, Kotlin, Swift, Ruby, PHP, .NET, Rust, Elixir or Other | Shows the matching environment rules |
The icons found this way can become the project's icon (**Icon** in Settings). Removing a
platform forgets what it was and its icon. The App Store listing goes when neither an iOS nor a
Mac app is left.
When events from the last 30 days come from platforms the project doesn't list yet, Settings
says so and offers **Add them**. Event platforms map to project platforms like this: `ios`,
`tvos` and `visionos` are an iOS app, `macos` a Mac app, `android` an Android app, `web` a
website, and `api`, `node`, `python`, `go` and `jvm` a server (with its language when it's known). A
website or an Android app opens as a card to fill in, since it needs its address or package.
Only owners can change the platforms.
## Filtering by platform [#filtering-by-platform]
- **Top bar:** when a project hears from more than one platform, the environment picker adds a
**Platform** section listing each event platform seen in the last 30 days, plus **All
platforms**. The choice is remembered per project in your browser and applies to every page.
See [Environments and platforms](/dashboard/environments-and-platforms).
- **Explorer:** the **Platform** filter takes one or several values, or excludes them
("Platform is not web").
Both filter by the `platform` on each event, not by the project's list.
# Retention
> How long a project keeps its events, and what happens when you change it.
Source: https://docs.lyrelog.com/concepts/retention
Each project keeps its events for a fixed time: 7, 14, 30, 60, 90 or 180 days, or 1 year. When an
event is older than that, it is deleted on its own.
- **Lengthening** it applies right away.
- **Shortening** it asks first: events older than the new limit are deleted for good, within a
few hours (the storage removes them as it merges its parts). Newer ones stay.
An event whose `ts` is older than the project's retention, or more than a day ahead, is stored at
its arrival time, with the time it was sent in the attribute `_lyrelog_ts_clamped` (the case of a
device whose clock is wrong). Send current times.
A new project keeps events for 30 days, or for the plan's longest if that's shorter (7 days on
Free).
Change it in [Settings](/projects/settings#retention). Only an owner can. **Details** in the
same page shows the current value.
## Retention and your plan [#retention-and-your-plan]
Each plan keeps events for up to a number of days:
| Plan | Longest retention |
|---|---|
| Free | 7 days |
| Pro | 30 days |
| Business | 1 year |
| Unlimited | As the project says, up to 10 years |
Settings only offer what your plan keeps, and never more than 1 year. Unlimited is given by
Lyrelog, not sold: to keep a project's events for longer than a year on it, write to
hello@lyrelog.com and Lyrelog sets it for you. If the plan changes to one that keeps less (a plan
given until a date that ended, for example), projects kept longer are shortened to the plan's
days within a few minutes, and older events are deleted with them. Moving to a longer plan
doesn't bring deleted events back; it lets you set a longer retention from then on.
The plan also counts events per organization per month: see [Plans and usage](/account/plans).
# Users, sessions and installs
> The three ids that tie events to a person, a visit and a device.
Source: https://docs.lyrelog.com/concepts/users-sessions-installs
| Id | Who sets it | What it means |
|---|---|---|
| `user_id` | Your app (`setUser`) | Your own id for the person: an account id, a player id. Up to 128 bytes. |
| `session_id` | The SDK | One visit. On a device, a new session starts after 30 minutes without any event; on a server, see below. |
| `install_id` | The SDK | One installation of the app: a random UUID kept on the device. |
## Users [#users]
Call `setUser` once you know who the person is, and every following event carries that id. Pass
`nil` / `null` / `None` / `""` to clear it (on sign-out). Lyrelog never makes up a user id: events
logged before `setUser` have none.
Each project picks the word it uses for its people (users, players, customers...) in
[Settings](/projects/settings). The dashboard uses it everywhere: the **Players** page of a
game is the **Customers** page of a shop.
## Sessions [#sessions]
How each SDK makes sessions:
| SDK | Session |
|---|---|
| Swift | A new one after 30 minutes without an event (`sessionTimeout`) |
| Android | A new one after 30 minutes without an event (`sessionTimeoutMillis`) |
| React Native, Flutter | The native SDK's: a new one after 30 minutes without an event (`sessionTimeoutMs`, `sessionTimeout`) |
| JavaScript, browser | One per tab, kept in `sessionStorage` with the time of the last activity, so a reload continues it; a new one after 30 minutes idle |
| JavaScript, Node | One per process, for as long as it runs |
| Python | One per process, and a new one after 30 minutes without an event (`session_timeout`) |
| Go | One per process, for as long as it runs |
| JVM | One per process, for as long as it runs |
On a server a session says little about a person: group by `user_id` instead.
Reports that arrive later, like a crash reported on the next launch, keep the time they
happened. Swift's have no session; an Android crash keeps the session it ended.
## Installs [#installs]
The install id survives launches and updates but not a reinstall. It is not an advertising
identifier and isn't linked to anything else on the device. On Android it lives in
`noBackupFilesDir`, so it's never in a backup restored on another device. On the web it lives in
`localStorage`. On servers (Node, Python, Go, the JVM) it is a new id for each process. React Native and
Flutter apps keep the native SDK's.
The user id isn't kept: call `setUser` again on each launch once you know who the person is.
# Verified events
> Events sent with a server key, or by your own Apple or Android app proven by the device, are marked verified, so you can tell them apart from events anyone holding the public key could have sent.
Source: https://docs.lyrelog.com/concepts/verification
An ingest key ships inside your app or your web page, so anyone can copy it and send events that
look like your app's. Lyrelog marks the events it can tell apart from those as **verified**, in
three ways:
- events sent with a **server key**, a secret that only your servers hold,
- events sent by **your own Apple app on a real device**, which Apple proves with
[App Attest](#apple-apps-app-attest), and
- events sent by **your own Android app on a real device**, which the device's secure hardware
proves with [Key Attestation](#android-apps-key-attestation).
## What verified means [#what-verified-means]
A verified event can't have been sent by someone who copied the public key out of an app or a
web page. With a server key, it came with a key that only the project's servers hold. With App
Attest, it came from the project's genuine app, signed by its team, on a genuine Apple device.
With Key Attestation, it came from the project's genuine Android app, signed with the project's
certificate, on a real Android device with its original, locked system.
It doesn't prove that what the event says is true. A server can send a wrong value, and someone
using the real app on a jailbroken device could still make it send events. A verified event is
only as trustworthy as the code that sent it.
Events sent with the public ingest key and no proof of the app are **not verified**: anyone
holding that key could have sent events just like them. That is most events from web pages and
from apps that don't use App Attest or Key Attestation, and it is expected.
## Who verifies [#who-verifies]
| Sender | Key | Its events | `verified_by` |
|---|---|---|---|
| Your server | Send events from a server, `lyr_srv_` | Verified | `server` |
| Your Apple app on a real iPhone, iPad or Apple Watch, [set up for App Attest](#apple-apps-app-attest) | Send events, `lyr_ing_` | Verified | `app_attest` |
| Your Android app on a real device, [set up for Key Attestation](#android-apps-key-attestation) | Send events, `lyr_ing_` | Verified | `key_attestation` |
| Anything else with the ingest key | Send events, `lyr_ing_` | Not verified | empty |
| Anything with a full-access key | Full access, `lyr_adm_` | Not verified | empty |
Lyrelog sets this on every event at ingest, from the key the batch came with and, for an ingest
key, the App Attest or Key Attestation token it carries. A client can't set it: a line that sends `verified_by`
itself is rejected with `unknown fields: verified_by`.
A server key can only append events, like an ingest key; it can't read them. See
[Keys](/concepts/keys) for how to make one.
## In the dashboard [#in-the-dashboard]
- In the events list, a small shield next to the event name marks a verified event.
- An opened event shows a **Verified** badge in its header. Under **Context**, **Sender** says
**Verified, server key**, **Verified, App Attest**, **Verified, Key Attestation** or
**Not verified, public key**.
- In the [explorer](/dashboard/explorer), the **Filter** menu has a field **Verified by**
with the values **Server key**, **App Attest**, **Key Attestation** and **Not verified** (in
the URL: `server`, `app_attest`, `key_attestation` and `none`). Pick all but **Not verified**
to see only verified events, or **Not verified** for the rest.
The [read API](/read-api) returns `verified_by` on each event (`"server"`, `"app_attest"`,
`"key_attestation"`, or `""` when not verified) and filters by it with `verified=server`,
`verified=app_attest`, `verified=key_attestation` or `verified=none`, or several at once
(`verified=server|app_attest|key_attestation`).
## Servers [#servers]
A backend (Node, Python, Go, Java or Kotlin on the [JVM](/sdks/jvm), or `curl` from a server)
should send with a server key, `lyr_srv_...`:
its events are verified, and it has no [daily limit per address](#the-daily-share-of-one-address).
Give the SDK the server key where the examples show `lyr_ing_...`; nothing else changes.
Keep it like any secret: in your server's environment or secret store, never in an app, a web
page or a repository. If it leaks, revoke it and make another.
## Apple apps (App Attest) [#apple-apps-app-attest]
Apple's App Attest lets an app prove to a server that it is the genuine app, signed by its team,
running on a genuine Apple device. The [Swift SDK](/sdks/swift#verified-events)
does it for you, and so do the [React Native](/sdks/react-native#attestation) and
[Flutter](/sdks/flutter#verified-events) SDKs on iOS, through the Swift SDK. Lyrelog stores
the events of a proven app as verified (`verified_by` is `app_attest`).
### Set it up [#set-it-up]
1. Find your app's **App ID**: your Team ID, a dot and the bundle id, like
`ABCDE12345.com.example.app`. The Team ID is in your Apple Developer account, under
**Membership**.
2. In Lyrelog, open [Project settings](/projects/settings#verified-events-from-your-apple-apps).
The section **Verified events from your Apple apps** is there when the project has the iOS app
platform. Add the App ID with **Add**. An owner can add up to 10, one per app (an iPhone app
and its watch app have different bundle ids).
3. In Xcode, add the **App Attest** capability to the app target (Signing & Capabilities). That
is the entitlement `com.apple.developer.devicecheck.appattest-environment`. Set it to
`production` for App Store and TestFlight builds. Without it Apple uses its development
environment, which also verifies.
4. Use the Swift SDK. Its option `appAttest` is `true` by default, so there is nothing else to
code. The same goes for React Native and Flutter (their option is `attest`): the project's
settings are the same, since the Swift SDK underneath does the work.
To turn it off, remove the App IDs (events arrive unverified, as before), or set
`appAttest: false` in the app.
### How it works [#how-it-works]
- Once per install, the SDK makes a key in the device's Secure Enclave and Apple attests it over
a one-time challenge from Lyrelog. Lyrelog checks Apple's certificate chain and that the app is
one of the project's App IDs, and keeps the key's public half: one per install, deleted after
180 days unused.
- The SDK then gets a token, valid for a day, and sends it with each batch. It renews the token
with a signature from that key (an assertion), whose counter can't be replayed.
- Sending never waits for this. Until the app has a token, and whenever anything fails, events
are sent and stored unverified. A batch is never refused because of App Attest.
### Where it doesn't apply [#where-it-doesnt-apply]
App Attest works on real iPhones, iPads and Apple Watches. These send unverified events, even
with everything set up:
- Macs (Apple doesn't offer App Attest there),
- the simulator,
- most app extensions,
- devices that don't support App Attest.
The routes and the header are in the [HTTP API](/http-api#apple-app-attest).
### Accept only verified events from the iOS app [#accept-only-verified-events-from-the-ios-app]
Off by default. In the same settings section, **Accept only verified events from the iOS app**
makes Lyrelog hold back every unverified batch whose events say `platform: ios`: it answers
`425 Too Early`, and the SDK keeps the batch and sends it again later. A new install's first events
wait a few seconds for its token and then arrive verified, so nothing is lost there.
Turn it on only when everyone has a version of the app with App Attest set up. Until then, events
from older versions, from the simulator and from an iPad app running on a Mac can never prove
themselves: they wait on the device, up to what the SDK keeps (20 MB and 7 days), and are never
stored. Events from other platforms, and from a server key, are accepted as before.
## Android apps (Key Attestation) [#android-apps-key-attestation]
Android's Key Attestation lets an app make a key inside the phone's secure hardware (its trusted
execution environment, or a StrongBox chip) and get a certificate chain from the device, signed
up to Google, that describes the key, the app and the state of the phone. Lyrelog checks that
chain itself: no Google account, Play Integrity or Google Cloud project is needed. The
[Android SDK](/sdks/android#verified-events) does it for you, and so do the
[React Native](/sdks/react-native#attestation) and [Flutter](/sdks/flutter#verified-events)
SDKs on Android, through the Android SDK. Lyrelog stores the events of a proven app as verified
(`verified_by` is `key_attestation`).
### Set it up [#set-it-up-1]
1. Find your app's **package** (its application id, like `com.example.app`) and the **SHA-256
fingerprint of the certificate it's signed with**:
- For builds installed from Google Play, Google signs the app: in Play Console, open the app,
then **Test and release**, **App integrity**, and copy the SHA-256 of the **App signing key
certificate**.
- For builds you sign yourself (an upload key, or the debug key in development), run
`./gradlew signingReport` and copy the SHA-256 of that variant.
2. In Lyrelog, open [Project settings](/projects/settings#verified-events-from-your-android-apps). The section **Verified events
from your Android apps** is there when the project has the Android app platform. Add the
package and the fingerprint with **Add**; add the same package again with another fingerprint
for each certificate that signs builds that send events (up to 5 per package, 10 packages).
3. Use the Android SDK. Its option `attest` is `true` by default, so there is nothing else to
code. The same goes for React Native and Flutter: the project's settings are the same, since
the Android SDK underneath does the work. In a React Native or Flutter project,
`./gradlew signingReport` runs in the app's `android` folder.
To turn it off, remove the packages (events arrive unverified, as before), or set
`attest = false` in the app.
### What is checked [#what-is-checked]
- The chain is signed, certificate by certificate, up to one of Google's attestation roots, and
none of its certificates is on Google's list of revoked ones.
- The key lives in the phone's secure hardware, was made there, and answers a one-time challenge
from Lyrelog.
- The phone booted its original, verified system and its bootloader is locked.
- The app is one of the project's packages, signed with one of its certificates.
Lyrelog then keeps the key's public half (one per install, deleted after 180 days unused) and
gives the app a token, valid for a day, that it sends with each batch. It renews the token by
signing a new one-time challenge with that key. Sending never waits for this: until the app has
a token, and whenever anything fails, events are sent and stored unverified. A batch is never
refused because of Key Attestation.
### Where it doesn't apply [#where-it-doesnt-apply-1]
These send unverified events, even with everything set up:
- emulators (they have no secure hardware, and their chains don't lead to Google),
- rooted phones, phones with an unlocked bootloader or a custom system,
- phones without hardware-backed keys (rare since Android 8),
- builds signed with a certificate the project doesn't list.
The routes are in the [HTTP API](/http-api#android-key-attestation).
### Accept only verified events from the Android app [#accept-only-verified-events-from-the-android-app]
Off by default, and it works like [the iOS one](#accept-only-verified-events-from-the-ios-app):
with it on, every unverified batch whose events say `platform: android` gets `425 Too Early` and
waits on the device. Turn it on only when everyone has a version with Key Attestation: events from
older versions, emulators and rooted or unlocked phones can never prove themselves and are never
stored.
## Web pages, through your own server [#web-pages-through-your-own-server]
A web page can't hold a server key: anything in the browser can be read. To get verified events
from a page, relay them through your own backend. The page sends to a route on your site, and the
route forwards the batch to Lyrelog with the server key.
Be clear about what that proves. These events are verified only in the sense that they passed
through your server. Anyone can post to a route on your site, so **the relay should accept events
only from your own signed-in sessions**, and cap what one session sends. A relay that takes
anything from anyone verifies nothing.
In the page, point the [JavaScript SDK](/sdks/javascript)'s `endpoint` at the relay. It is
a base URL: the SDK posts to `/v1/events:batch`. `apiKey` can't be empty, but the relay
replaces it, so any placeholder works:
```ts
export const log = Lyrelog.init({
endpoint: "https://example.com/api/lyrelog", // posts to /api/lyrelog/v1/events:batch
apiKey: "relay", // replaced by the server key on your server
});
```
The relay, as a Next.js route handler (`app/api/lyrelog/[...path]/route.ts`):
```ts
import { getSession } from "@/lib/auth"; // your own sign-in
export async function POST(request: Request) {
const session = await getSession(request);
if (!session) return new Response(null, { status: 401 });
const encoding = request.headers.get("Content-Encoding");
const upstream = await fetch("https://ingest.lyrelog.com/v1/events:batch", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LYRELOG_SERVER_KEY}`, // lyr_srv_..., server only
"Content-Type": request.headers.get("Content-Type") ?? "application/x-ndjson",
...(encoding ? { "Content-Encoding": encoding } : {}),
},
body: await request.arrayBuffer(),
});
const headers = new Headers({ "Content-Type": "application/json" });
const retryAfter = upstream.headers.get("Retry-After");
if (retryAfter) headers.set("Retry-After", retryAfter);
return new Response(await upstream.text(), { status: upstream.status, headers });
}
```
Worth knowing:
- Pass the status and `Retry-After` back unchanged: the SDK decides from them whether to retry
or drop a batch.
- A `401` or `403` makes the SDK stop sending until the page reloads. Start the client once the
visitor has signed in, not before.
- The [country](/concepts/countries) comes from the address that sends the batch to
Lyrelog, which is now your server's. Relayed events carry your server's country, not the
visitor's.
- Add the relay's address to your Content Security Policy's `connect-src` if you set one
(`'self'` covers a route on the same site).
## Other apps and web pages [#other-apps-and-web-pages]
Events from Apple apps without App Attest, from Android apps without Key Attestation, and from
web pages that send directly use the public ingest key with no proof of the app, so they are not verified. A web page
can get verified events [through your own server](#web-pages-through-your-own-server). Two limits
keep a copied key from doing much harm:
- the plan's [monthly events](/account/plans), for the whole organization, and
- the daily share of one address, below.
## The daily share of one address [#the-daily-share-of-one-address]
With a public key (an ingest key, or a full-access key), one sending address may send at most a
fiftieth of the plan's monthly events in a UTC day, across the organization's projects. IPv6
addresses count per /64. Only events that aren't [verified](#who-verifies) count.
| Plan | Events a day from one address |
|---|---|
| Free | 20,000 |
| Pro | 200,000 |
| Business | 4,000,000 |
| Unlimited | No limit |
That is far more than one device sends. It exists so that a key copied out of an app can't
spend the organization's month from one machine. Verified events (from a server key, App
Attest or Key Attestation) don't count toward it.
Past it, that address gets `429` with a `Retry-After` of at most an hour, until the next UTC
day. Other addresses keep sending. The SDKs retry it like any `429`, keeping events within their
queue limits. The body is in the [HTTP API](/http-api#429-the-daily-share-of-one-address).
If one of your servers reaches it, it should be using a server key.
# Command menu
> Press ⌘K to find an event, a person or a session, or to jump to any page.
Source: https://docs.lyrelog.com/dashboard/command-menu
Press ⌘ K (Ctrl K on Windows and Linux) anywhere in
the dashboard, or click the search pill in the top bar.
## Find [#find]
Type or paste at least two characters:
- **An event id**: opens it on its person's page, or shows its session in the explorer when it
has no user.
- **A user id** (named with your project's word): opens that person's page.
- **A session id, or its start**: opens the session on its person's page.
- **An event name**: lists events named like it. Pick one to search for it.
- **An area**: lists matching areas. Pick one to filter the explorer by it.
**Search "…" in** runs the text in the explorer instead: as a search of event names, as a user
id, or as a session id. A pasted event id that isn't found offers a search over the last 30
days.
## Jump [#jump]
**Go to** lists the project's pages: Events, Insights, Sessions, Errors, the people page (Users,
Players...), Releases, Project settings and API keys, plus **Go live** on the explorer. Type to
narrow the list.
**Projects** opens another project. **Appearance** switches between the light and dark theme.
Move with the arrow keys, open with Enter, close with Esc.
## The account menu [#the-account-menu]
The round button with your initial, at the right of the top bar, opens the account menu:
- **Light**, **Dark** or **Match the system**: the dashboard's appearance.
- **Text size**: three sizes, Default, Large and Extra large, for the whole dashboard.
- **Your account**, **Organization** and **Plan and usage**, and signing out.
The appearance and the text size are remembered in this browser, not in your account.
# Environments and platforms
> The picker in the top bar decides which part of a project every page shows.
Source: https://docs.lyrelog.com/dashboard/environments-and-platforms
The pill in the top bar, next to the project, shows the current environment, and the platform
when one is picked: "production · iOS".
## Environment [#environment]
The menu lists the environments seen in the last 30 days with their event counts, and **All
environments**. Every page about events follows it: the explorer, insights, errors, sessions,
people and releases.
The choice is remembered per project in your browser. Until you pick one, the dashboard opens on
the project's default environment, `production` unless an owner changes it in
[Settings](/projects/settings). If the environment you're on has no events in the last 30
days, the menu still shows it, marked "no events".
## Platform [#platform]
When a project's events come from more than one platform (an iOS app and its backend, say), the
same menu adds a **Platform** section with each platform seen in the last 30 days, its event
count, and **All platforms**. It is remembered per project in your browser too.
The menu lists the `platform` values on the events (`ios`, `node`, `api`...), shown by name
(iOS, Node, API). It doesn't depend on the platforms set up in Settings. See
[Platforms](/concepts/platforms).
For a one-off look, use the explorer's **Platform** filter instead.
# Errors
> Every kind of problem once, sorted by how many people it reached.
Source: https://docs.lyrelog.com/dashboard/errors
The **Errors** page groups `error` and `critical` events by their area and event name, so each
kind of problem appears once. The heading sums it up: how many kinds of problem, how many are
new in the range, and how many people they reached.
Pick the last 24 hours, 7 days (the default) or 30 days.
## Each problem [#each-problem]
- **Its name**, its area, when it was first seen, and the app versions it appears in. Problems
first seen inside the range are marked **New**.
- **Over the range**: bars of how often it happened.
- **Events** and **Users** (your project's word): how many of each it reached.
- **Trend**: the change against the period just before, as a percentage. Below 10 events before,
it says how many there were instead ("none before", "4 before").
- **Last seen**.
The list is sorted by how many people each problem reached.
## Using it [#using-it]
- **Include warnings** adds `warning` events.
- **Filter errors** narrows the list by area or name.
- Click a problem's name to see its events in the [explorer](/dashboard/explorer).
- **Play back the latest** opens the person who hit it most recently and plays back that session
from the error. See [Sessions and playback](/dashboard/sessions).
Crash and hang reports from the [Swift SDK](/sdks/swift#crashes-and-hangs) show up here as
`app_crashed` and `app_hung` in the `diagnostics` area. Crashes from the
[Android SDK](/sdks/android#crashes) are `app_crashed` in the same area, so both
platforms' crashes sit together. The [React Native](/sdks/react-native#errors-nobody-caught)
and [Flutter](/sdks/flutter#native-crashes) SDKs send the native SDKs' crash reports too,
and React Native adds fatal JavaScript errors as `app_crashed` beside them. Errors nobody caught
that didn't end the app (an unhandled promise rejection, a Dart error, an uncaught exception on a
[JVM](/sdks/jvm#uncaught-exceptions) thread) are `exception` events with `handled: false`.
# Events explorer
> Search what happened, narrow it down with filters, and open any event.
Source: https://docs.lyrelog.com/dashboard/explorer
The **Events** page is where a project opens (`app.lyrelog.com/p/`). From the top:
four cards, a chart of the range, where people are, and the list of events, newest first.
Like every page about events, it shows the environment and platform picked in the
[top bar](/dashboard/environments-and-platforms).
## Time range [#time-range]
Pick the last hour, 6 hours, 24 hours, 7 days or 30 days. The page opens on 24 hours.
**Drag across the chart** to zoom into a moment; **Zoomed in, reset** goes back to 24 hours.
When errors jump, the chart marks the stretch with a note such as "12 errors, 10:40 to 10:55":
click it to zoom in there.
**Go live** follows new events as they arrive. Click it again to stop. It works only on the
preset ranges, not on a zoomed-in one.
## The cards [#the-cards]
**Events**, **Users** (your project's word for its people), **Sessions** and **Errors** in the
range, each with a small trend. On a preset range each card also compares with the period just
before ("vs the day before").
Click **Errors** to see the most frequent errors and the errors by area. Pick one to filter the
list by it.
## Where people are [#where-people-are]
A map of where your people are, with a ranked list of countries. A person's country comes from
their events, else from their device's region. See [Countries](/concepts/countries).
## Search [#search]
The search box (press / to focus it) looks in event names and areas, and matches any id
you paste exactly: an event id, a user id, a session id or an install id.
Paste an event id from outside the range and the page tells you when it happened, with **Show
it** to jump there.
## Filters [#filters]
Choose **Filter by…** and a field, then pick one or more values. The menu lists the values found
in the current range, with their counts.
| Field | What it matches |
|---|---|
| Area | The event's category |
| Level | Any set of levels |
| Event | The message (event name) |
| User | The user id (named with your project's word: Player, Customer...) |
| Session | The session id |
| Platform | `ios`, `web`, `python`... |
| App version, OS version, Device | From the event's context |
| Country | Where the person is: the country, else the locale's region |
| Locale | The device's locale |
| Attribute | Anything you sent in `attrs`, by its path (`gc.ok`) |
Each filter becomes a **token** above the list, like "Area is any of checkout, sync". Click a
token to change it, or its cross to remove it. **Clear all** removes every filter.
- **Several values** in one filter mean "any of these".
- **Is not** excludes them instead: "Area is not sync, chat". Every field except Level offers it.
- **Attributes** work the same way: pick an attribute name, then its values.
Under the search, the most frequent areas show as chips: click several to see any of them, or
**All areas** to clear. The level chips on the right toggle levels on and off. The floating dock
at the bottom has **Only errors**, **Go live** and **Back to the top**.
Filters live in the URL, so a filtered view can be bookmarked or shared with someone on the
project. The environment and platform picked in the top bar aren't part of the link: whoever opens
it sees their own choice.
## Breakdown [#breakdown]
**Breakdown** shows the most frequent events and the spread by app version, OS version, device
and locale for what's on screen. Click a value to filter by it.
## Opening an event [#opening-an-event]
Click an event (or move with j and k, close with Esc) to see
it whole:
- **The header**: its level, area, time and name, with buttons to filter by **This user**,
**This session** or its device, a copy button for the event id, and **Play back the session**
when it has a user and a session.
- **Attributes**: each one with **Only events where...** and **Hide events where...**, and a copy
button.
- **Payload**, pretty-printed, if it has one. **Raw event** shows the whole event instead, and
**Copy as JSON** copies what's shown.
- **Context**: the user (a link to their page), the session and its length, the app version and
build, the system, the device and the locale.
- **Around this moment**: the event's session as a strip, with the events just before and after
it.
An event without a session was reported outside one, such as a crash report that arrives on the
next launch.
# Insights
> Trends, values, failure rates and funnels, built for the questions logs answer.
Source: https://docs.lyrelog.com/dashboard/insights
Insights lean to what logs measure: how often something happens, how long it takes, how often it
fails. Product funnels for marketing belong in a product analytics tool; here they're for flows
that break.
Choose **Trends**, **Rates** or **Funnels** at the top, and a range of 24 hours, 7 days (the
default) or 30 days. Like every page about events, Insights follows the environment and platform
in the [top bar](/dashboard/environments-and-platforms).
Every chart leaves out the bucket still in progress, so the last point never looks like a drop.
The whole builder lives in the URL, so any chart can be shared.
## Trends [#trends]
*How often things happen, to how many, or how long they take.*
1. **Add event**: one or more events to chart.
2. Choose what to count:
- **Times**: how many events.
- **Users** (your project's word): how many different people.
- **A value**: a statistic of a numeric attribute.
3. **Break down by** app version, country, OS version, device, area or locale. The 8 biggest
groups are named; the rest add up to "Other".
### Values [#values]
With **A value**, pick the **Statistic** (Average, Median, p90, p95, p99 or Highest) and the
**Attribute**, for example the p95 of `latency_ms`. Events without that attribute are skipped,
and a bucket with none is drawn as a gap. Units come from the attribute's name: `_ms` is
milliseconds, `seconds` is seconds, `bytes` is bytes.
Log durations and sizes as numbers (`latency_ms: 412`) to measure them.
## Rates [#rates]
*What share of attempts fail, over time and by version.*
Pick **What failed** (`leaderboard_submit_failed`) and **What was tried** (`leaderboard_submit`).
The chart shows failures over attempts in each bucket, and can be broken down like a trend.
## Funnels [#funnels]
*How many get from one step to the next.*
Add two to eight steps. A funnel follows each person (by `user_id`) through the steps in order,
within **Time to finish** (5 minutes, 1 hour, 1 day or 7 days), and shows how many reach each one
and the median time between steps. Events without a `user_id` don't count. Reorder steps with
**Move earlier** and **Move later**.
## Saved views [#saved-views]
**Save what's on screen** keeps the current chart or funnel under a name. Saved views show up for
everyone on the project. Click one to open it, or hover it and click the bin to delete it.
# People
> The people your app talks to, named as your project names them, and everything that happened to each.
Source: https://docs.lyrelog.com/dashboard/people
This page takes the project's word for its people: **Users** by default, **Players** for a game,
or whatever an owner sets in [Settings](/projects/settings). The same word names the tab,
the filters and the cards everywhere else.
## The list [#the-list]
Everyone with a `user_id` in the range (24 hours, 7 days or 30 days; 7 days by default). Sort by
**Recent**, **Most active**, **Most errors** or **Newest**.
Each row shows the person's id and how long ago they were first seen, the device and app version
they last used, their sessions, events and errors, and when they were last seen. Hover the
errors to see the share of their sessions that saw one.
To find someone, type part of their id in the search box.
## One person [#one-person]
Click a person to open their page. It shows:
- Their latest device, system, app version and locale, and when they were last seen.
- Cards for their **Sessions**, **Events**, **Errors** and **Minutes per session** over the
range (24 hours, 7 days or 30 days).
- Each session as a card, newest first: when it started, how long it lasted, its events,
warnings and errors, the app version, and a strip of its events. Sessions with errors open on
their own.
Click an event in a session to open it whole, as in the explorer. **Play back** replays the
session: see [Sessions and playback](/dashboard/sessions#playback). **Load earlier
events** appears when the person has more than fit on the page.
The command menu (⌘ K) opens a person directly from their id. Events with
no `user_id` don't belong to anyone and don't appear here.
# Releases
> Each app version, who has it, and how its sessions go.
Source: https://docs.lyrelog.com/dashboard/releases
**Releases** lists every app version seen in the range (24 hours, 7 days or 30 days; 7 days by
default), newest first. Versions are compared number by number, so `2.0.1` comes before `2.0`.
## Adoption [#adoption]
**Users by version** (your project's word) draws how people moved from one version to the next
over the range. Hover it to read each version's count at a moment.
## Each version [#each-version]
A card per version shows:
- The version, when it was first seen and last seen. The newest is marked **Newest**.
- The share of **error-free sessions**.
- The share of all people in the range who used it.
- Its **Sessions**, **Errors** and **Critical** events.
- **Events** and **Its errors** open the [explorer](/dashboard/explorer) filtered by that
version.
## Where versions come from [#where-versions-come-from]
Versions come from `resource.app_version`. The Swift SDK reads it from the app's bundle, the
Android SDK from the app's `versionName` (or `appVersion`), and the React Native and Flutter SDKs
through them. The JVM SDK takes the started jar's `Implementation-Version`. The other SDKs take it
from `release` (`Release` in Go). Without one, Node uses `npm_package_version` and Go uses the main
module's version from the build info.
# Sessions and playback
> Find sessions by what happened in them, then play one back.
Source: https://docs.lyrelog.com/dashboard/sessions
A session is one visit, from the first event to 30 minutes of silence. See
[Users, sessions and installs](/concepts/users-sessions-installs).
## Finding sessions [#finding-sessions]
The **Sessions** page lists the sessions in the range (24 hours, 7 days or 30 days; 7 days by
default). Narrow them down with:
- **Where an event happened**: only sessions that contain a given event. The session's other
events still count.
- **With errors**: only sessions with an error.
- **Length**: any length, or over 1, 5 or 15 minutes.
Sort by **Recent**, **Longest**, **Most errors** or **Busiest**. **Show more** loads the next
page.
Each row shows:
- Who it was, how long ago it started, and the device, app version and country.
- How long it lasted, as a bar against the longest in the list.
- What happened: the first error, or else the first and the last event.
- How many events and errors.
Click the person to open their page on that session, or the play button to play it back.
## Playback [#playback]
Playback lives on the [person's page](/dashboard/people#one-person), on each session's card.
Click **Play back** there, or **Play back this session** on the Sessions page, **Play back the
session** on an open event, or **Play back the latest** on the Errors page. The last three jump
to the person's page and start playing on their own.
Playback replays the session's events in order on its strip, with the silences fast-forwarded:
each gap between two events plays in 0.2 to 1.1 seconds, whatever its real length, so events
arrive at a steady beat. The event being played stays in view in the list below.
- **Pause** and **Resume** stop and carry on.
- **Play again** starts over once it ends.
- **Show the events** and **Hide the events** open and close the list.
Playback replays logged events, not the screen: what you see is what the app sent.
# HTTP API
> Send events without an SDK. The ingest endpoint, every field and limit, and what a client should do with each answer.
Source: https://docs.lyrelog.com/http-api
The SDKs use this API, and so can anything that speaks HTTP. When this page and an SDK disagree,
this page wins.
## The endpoint [#the-endpoint]
```http
POST https://ingest.lyrelog.com/v1/events:batch
```
| Header | Value |
|---|---|
| `Authorization` | `Bearer lyr_ing_...` (an ingest key), `Bearer lyr_srv_...` (a server key), or a full-access key |
| `Content-Type` | `application/x-ndjson` (`application/jsonl` works too) |
| `Content-Encoding` | `gzip` (optional, recommended), or `identity` / none for plain text |
| `X-Lyrelog-Attestation` | Optional. A token from an Apple or Android app with an ingest key (see [Apple App Attest](#apple-app-attest) and [Android Key Attestation](#android-key-attestation)) |
A read key can't send events: it gets `403`. From a server, use a server key: its events are
[verified](/concepts/verification) and one address has no daily share. Apps and web pages
use the ingest key; an Apple app's events can be verified with [App Attest](#apple-app-attest), an
Android app's with [Key Attestation](#android-key-attestation).
## The body: NDJSON [#the-body-ndjson]
One JSON object per line, one line per event.
- At least one event and at most **2,000 lines** per request. An empty body, or one with more
lines, gets `400` for the whole batch.
- At most **4 MiB** on the wire and **4 MiB** once decompressed, and **1 MiB** for one line
(a longer line is rejected on its own).
- Blank lines are ignored but still count in the line numbering (so errors point at the right
line).
```json
{"event_id":"6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f","ts":"2026-11-18T10:00:00.123Z","level":"info","category":"checkout","message":"checkout_done","user_id":"user-1","install_id":"8c1d...","session_id":"2f9a...","attrs":{"items":3,"latency_ms":412,"payment":{"method":"card"},"tags":["a","b"]},"payload":{"response":"..."},"resource":{"app_id":"com.example.app","app_version":"2.0","app_build":"202611181200","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,1","locale":"es_ES","sdk":"lyrelog-swift/0.1.0","environment":"production","platform":"ios"}}
```
## Fields [#fields]
| Field | Required | Rules |
|---|---|---|
| `event_id` | Yes | A UUID made once per event. A resend with the same id and `ts` is collapsed. The same id twice in one batch rejects the second line. |
| `ts` | Yes | RFC 3339 with a zone. Up to a day ahead of the server it is kept as sent. Further ahead, or older than the project's retention, the event is stored at the arrival time and the time it was sent goes in the attribute `_lyrelog_ts_clamped`. |
| `level` | No | `trace`, `debug`, `info` (default), `notice`, `warning`, `error`, `critical` |
| `category` | No | Up to 64 bytes: the area of the app (`checkout`, `sync`) |
| `message` | Yes | Up to 2,048 bytes. A stable event name (`checkout_done`), not prose. |
| `user_id` | No | Up to 128 bytes |
| `install_id` | No | Up to 128 bytes |
| `session_id` | No | Up to 128 bytes |
| `attrs` | No | See below |
| `payload` | No | Any JSON up to 64 KiB once serialized. Stored compressed, not searchable. |
| `resource` | No | See below |
**Unknown fields are rejected**, so a typo surfaces instead of disappearing.
### `attrs` [#attrs]
Small fields to filter and chart by.
- Values: strings (up to 1,024 bytes), numbers, booleans, null, arrays of strings (up to 64
items) and nested objects (up to 4 levels).
- At most **200 leaves** in total.
- Names: up to 128 bytes, no dots (nest an object instead), no leading `_`.
### `resource` [#resource]
Only these keys, each up to 64 bytes:
`app_id`, `app_version`, `app_build`, `os_name`, `os_version`, `device_model`, `locale`, `sdk`,
`environment`, `platform`.
`environment` and `platform` are lowercase letters, digits, `-` and `_`, up to 32 characters,
starting with a letter or digit. Without an `environment`, the event is stored as
`production`. Without a `platform`, the server derives one from `sdk` and `os_name`.
### Added by the server [#added-by-the-server]
`country`: the ISO code of the address the batch came from, on every event of the batch. A client
can't set it, and the address isn't stored. See [Countries](/concepts/countries).
`verified_by`: `server` when the batch came with a server key, `app_attest` or `key_attestation`
when it came with an ingest key and a valid [App Attest](#apple-app-attest) or
[Key Attestation](#android-key-attestation) token, empty otherwise. A client can't set
it: a line that includes `verified_by` is rejected with
`unknown fields: verified_by`. See [Verified events](/concepts/verification).
## Responses [#responses]
Every answer is JSON. An error has an `error` field that says what went wrong.
| Status | Meaning | What the client does |
|---|---|---|
| `200` `{"accepted":n,"rejected":[{"line":i,"error":"..."}]}` | Stored. Rejected lines are invalid. | Delete the batch. Never resend the rejected lines. |
| `400`, `413`, `415`, any other 4xx | The batch itself is wrong | Delete it: it would fail again. |
| 3xx | Not an answer from the ingest: the endpoint is wrong | Don't follow it; fix the endpoint. |
| `401`, `403` | Unknown, revoked or read-only key | Stop sending until the next launch; keep the data. |
| `408`, `425`, `429`, 5xx, network error | Temporary | Keep the same bytes, retry with backoff, honor `Retry-After`. |
A batch is checked in this order: the key, then `Content-Type` and the declared size, then the
monthly quota, the daily share of one address and the rate limit (all before the body is read), then the body and its lines. A batch that fails one check gets that answer and stores
nothing. Rejected lines count against the rate limit. Batches sent at the same moment can go a
little past the monthly quota before it applies.
Revoking a key takes effect at once; allow up to a minute.
### `400`, `413`, `415`: the batch itself [#400-413-415-the-batch-itself]
| Status | `error` | What to fix |
|---|---|---|
| `415` | `Content-Type must be application/x-ndjson` | Send `application/x-ndjson` or `application/jsonl` |
| `400` | `unsupported Content-Encoding "br" (use gzip)` | Send `gzip`, or no `Content-Encoding` |
| `400` | `body is not valid gzip` | Compress the whole body with gzip |
| `400` | `empty batch` | Send at least one event |
| `400` | `too many events in one batch (max 2000)` | Split the batch |
| `413` | `body too large`, `body too large once decompressed` | Keep each batch under 4 MiB, before and after gzip |
### `429`: the monthly quota [#429-the-monthly-quota]
A Free organization includes 1,000,000 events a month, for all its projects together. Past that,
every batch gets `429` until the next month starts (the 1st, UTC), or until the organization
moves to another plan:
```json
{"error":"this organization's free plan includes 1000000 events a month and they're used: upgrade it, or events resume on 1 December","plan":"free","limit":1000000,"used":1000412}
```
| Field | Meaning |
|---|---|
| `error` | What happened, for a person to read |
| `plan` | The organization's plan |
| `limit` | The events the plan includes each month |
| `used` | The events counted so far this month |
`Retry-After` is the seconds until the next month, but never more than an hour, so an upgrade
takes effect soon. Treat it like any other `429`: keep the batch and send it again later. The
SDKs do this for you, within their queue's limits (see
[what waits where](/account/plans#at-the-free-limit)), and log one warning the first time.
The `plan` field is what tells this `429` apart from the other two: the daily share of one
address has `source_limit` instead, and the rate limit's body has only `error`.
### `429`: the daily share of one address [#429-the-daily-share-of-one-address]
With a public key (an ingest or full-access key), one address may send at most a fiftieth of the
plan's monthly events in a UTC day, for all the organization's projects together: Free 20,000,
Pro 200,000, Business 4,000,000, Unlimited no limit. IPv6 addresses count per /64. Verified
batches (a server key, or a valid App Attest or Key Attestation token) aren't limited this way. Past it, batches from that address get `429`:
```json
{"error":"this address sent 20000 events today with a public key of this organization, its share of the day: a server should use a server key, which has no such limit; events from here resume tomorrow (UTC)","source_limit":20000}
```
`source_limit` is the events one address may send a day. `Retry-After` is the seconds until the
next UTC day, at most an hour. Other addresses keep sending. Treat it like any other `429`; if a
server gets it, give that server a server key. Why it exists:
[Verified events](/concepts/verification#the-daily-share-of-one-address).
### `425`: verified events only [#425-verified-events-only]
A project can accept only verified events from a platform (an owner turns it on in the project's
settings; off by default). An unverified batch with an event from that platform gets
`425 Too Early`, `Retry-After: 30` and
`{"error":"this project accepts only verified events from ios: ...","verification_required":"ios"}`
(or `android`).
Nothing of the batch is stored. Keep it and send it again, with a valid
`X-Lyrelog-Attestation` token once you have one: the SDKs do this on their own.
[Verified events](/concepts/verification#accept-only-verified-events-from-the-ios-app).
### `429`: the rate limit [#429-the-rate-limit]
Each project takes at most 60,000 events a minute by default. A batch over it gets `429` with
`{"error":"rate limit for this project"}` and a `Retry-After` in seconds.
### `429`: unknown keys [#429-unknown-keys]
An address that sends more than 30 unknown keys in a minute gets `429` with `Retry-After: 60`.
A token that isn't shaped like a Lyrelog key gets `401` straight away.
### `503` [#503]
The server can't reach its database or storage right now, or it's busy with other batches. It
answers with `Retry-After: 5`. Retry the same bytes.
## Idempotency [#idempotency]
Delivery is at least once. When a retry might be a duplicate, resend **exactly the same lines**:
events with the same `event_id` and `ts` collapse into one. Never make new ids for a retry.
## Apple App Attest [#apple-app-attest]
An Apple app on a real iPhone, iPad or Apple Watch can prove it is the project's genuine app,
and its events are then stored with `verified_by` set to `app_attest`. The
[Swift SDK](/sdks/swift#verified-events) is the client (also under React Native and
Flutter) and does all of this on its own; this section is for reference. What it proves, and how to set it up:
[Verified events](/concepts/verification#apple-apps-app-attest).
The three routes take a JSON body and the project's **ingest key** as the bearer, and count
toward the project's rate like one event each. They answer `404` until an owner has added an App
ID in the project's settings, and `403` to any other key (a server key's events are verified
already). They have no CORS: they are for apps, not web pages.
| Route | Body | Answer |
|---|---|---|
| `POST /v1/attest/challenge` | `{}` | `{"challenge":"..."}`: single use, for 5 minutes, for this project only |
| `POST /v1/attest/key` | `{"key_id","attestation","challenge"}` | `{"token","expires_at"}` |
| `POST /v1/attest/token` | `{"key_id","assertion","challenge"}` | `{"token","expires_at"}`, or `404` for a key the project doesn't have: attest it again |
- `key_id` is the base64 key id that `DCAppAttestService` returns; `attestation` and `assertion`
are base64. The app passes the SHA-256 of the challenge's UTF-8 bytes as `clientDataHash`.
- `/v1/attest/key` is called once per install, with the attestation of a new key.
`/v1/attest/token` renews the token with an assertion made with that key. An attestation or
assertion that doesn't check out gets `400`.
- A token is valid for 24 hours. A batch carries it in the `X-Lyrelog-Attestation` header. A
valid one makes the batch verified and spares it the
[daily share of one address](#429-the-daily-share-of-one-address). Without one, nothing
changes. One that proves nothing (expired, another project's, or not a token) leaves the batch
unverified, and the answer carries `X-Lyrelog-Attestation: renew`, so the app gets a new one.
- A batch is never refused because of its token.
## Android Key Attestation [#android-key-attestation]
An Android app on a real device can prove it is the project's genuine app, signed with your
certificate, on a device that hasn't been tampered with. Its events are then stored with
`verified_by` set to `key_attestation`. The [Android SDK](/sdks/android#verified-events) is
the client (also under React Native and Flutter) and does all of this on its own; this section is for reference. What it proves, and how to set it up:
[Verified events](/concepts/verification#android-apps-key-attestation).
The same rules as App Attest: a JSON body, the project's **ingest key** as the bearer (`403` for
any other key), one event of the project's rate each, no CORS, and `404` until an owner has added
an Android app (its package and signing certificate) in the project's settings. The challenge
comes from the same route, `POST /v1/attest/challenge`.
| Route | Body | Answer |
|---|---|---|
| `POST /v1/attest/android/key` | `{"challenge","chain":[...]}` | `{"token","expires_at","key_id"}` |
| `POST /v1/attest/android/token` | `{"key_id","challenge","signature"}` | `{"token","expires_at"}`, or `404` for a key the project doesn't have: attest it again |
- `/v1/attest/android/key` is called once per install. The app makes an EC P-256 key in the
Android Keystore with the challenge's UTF-8 bytes as its attestation challenge, and sends the
key's certificate chain, leaf first, each certificate standard base64 DER. Keep the `key_id`
it answers with.
- `/v1/attest/android/token` renews the token: `signature` is the base64 ECDSA signature
(`SHA256withECDSA`, DER) over a new challenge's UTF-8 bytes, made with that key.
- A chain or signature that doesn't check out gets `400`. Right after the server starts, before
it has Google's list of revoked certificates, `/v1/attest/android/key` may answer `503` with
`Retry-After`: ask again later.
- Tokens work as App Attest's: 24 hours, in `X-Lyrelog-Attestation`, `renew` when one proves
nothing, and a batch is never refused because of its token.
## CORS [#cors]
The endpoint answers browsers from any origin, so a web page can send events directly:
| Header | Value |
|---|---|
| `Access-Control-Allow-Origin` | `*` |
| `Access-Control-Allow-Methods` | `POST, OPTIONS` |
| `Access-Control-Allow-Headers` | `Authorization, Content-Type, Content-Encoding` |
| `Access-Control-Expose-Headers` | `Retry-After` |
| `Access-Control-Max-Age` | `86400` |
The wildcard is safe because no cookies are involved and an ingest key can only append events.
The dashboard's own API has no CORS.
## Examples [#examples]
In these examples, the shell variable `$LYRELOG_KEY` holds one of the project's keys (set it
yourself: `export LYRELOG_KEY=lyr_srv_...`). From a server or a cron job, as here, use a server
key, `lyr_srv_...`; an ingest key, `lyr_ing_...`, works too, but its events aren't verified.
### One event [#one-event]
```bash
curl -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @- < batch.ndjson < batch.ndjson.gz
curl -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
-H "Content-Encoding: gzip" \
--data-binary @batch.ndjson.gz
```
### A rejected line [#a-rejected-line]
The second line has a typo, `mesage`:
```bash
printf '%s\n' \
"{\"event_id\":\"$(uuidgen | tr A-Z a-z)\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"message\":\"ok\"}" \
"{\"event_id\":\"$(uuidgen | tr A-Z a-z)\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"mesage\":\"typo\"}" |
curl -s -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer $LYRELOG_KEY" \
-H "Content-Type: application/x-ndjson" \
--data-binary @-
```
The first line is stored, the second is not:
```json
{"accepted":1,"rejected":[{"line":2,"error":"unknown fields: mesage"}]}
```
Common line errors:
| `error` | What to fix |
|---|---|
| `event_id must be a UUID string` | Send a UUID such as `6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f` |
| `ts must carry a time zone (use Z for UTC)` | `2026-11-18T10:00:00Z`, not `2026-11-18T10:00:00` |
| `message must be a non-empty string` | Every event needs a `message` |
| `unknown fields: ...`, `unknown resource fields: ...` | A typo, or a field Lyrelog doesn't take (also `verified_by` and `country`, which only the server sets) |
| `bad attribute name "..." in attrs` | An attribute name with a dot or a leading `_`: nest an object instead |
| `attrs.tags: arrays may only hold strings` | Arrays in `attrs` hold strings only |
| `event_id repeated in this batch` | Each event gets its own id |
## Health [#health]
```http
GET https://ingest.lyrelog.com/healthz
```
`200 {"status":"ok","storage":true,"database":true}`, or `503` with `"status":"degraded"` when
the storage or the database is down.
# Introduction
> Structured logs from your apps, sent to a hosted service, with a dashboard to search them and play back what happened to someone.
Source: https://docs.lyrelog.com/
Lyrelog records what happens inside your apps, one event at a time, and lets you read it back:
search every event, follow one person through a session, see which errors reached the most
people, chart how long a request takes on each version.
*The lyrebird records every sound it hears and plays it back. Lyrelog does that for your app.*
## What it is [#what-it-is]
- **Logs about what happened to a person.** A payment that was declined, a sync that
timed out, a screen someone left after two seconds. Each event has a stable name
(`payment_declined`), a level, an area of the app and a few fields you can filter and chart by.
- **A hosted service.** Your apps send events to `https://ingest.lyrelog.com`, and you read them
in the dashboard at [app.lyrelog.com](https://app.lyrelog.com). You don't run anything. Your
events are stored on Lyrelog's servers in Germany. Backups are kept for at most 30 days: on the
same servers, and as an encrypted copy in Backblaze's EU data center in the Netherlands that
Backblaze can't read.
- **SDKs that stay out of your code's path.** Logging copies the event and returns; batching, gzip,
retries and offline queues happen in the background. There are SDKs for
[Swift](/sdks/swift), [Android](/sdks/android),
[React Native](/sdks/react-native), [Flutter](/sdks/flutter),
[JavaScript](/sdks/javascript), [Python](/sdks/python), [Go](/sdks/go) and
[Java and Kotlin servers](/sdks/jvm), and a plain [HTTP API](/http-api) for anything else. The SDKs
aren't published yet: until they are, send events over the HTTP API.
- **The dashboard, and a command-line tool.** Read events in the browser, or from a terminal
with [`lyrelog`](/cli), which also writes JSON for scripts and coding agents.
## Early access [#early-access]
Lyrelog is in early access, by invitation. Ask for one on [lyrelog.com](https://lyrelog.com).
When it's your turn, you get an email with a link that makes your account and your
organization. See [Getting access](/account/getting-access).
The Free plan covers 1,000,000 events a month. Paid plans aren't open yet. See
[Plans and usage](/account/plans).
## What it isn't [#what-it-isnt]
Lyrelog is not product or marketing analytics. It has trends and funnels, but they are there to
find flows that break (what share of submits fail, on which version), not to measure campaigns
or conversion. Keep a tool like PostHog for that, and use Lyrelog for the question "what
happened to this person, and why".
It is also not a crash symbolicator or a tracing system: crash reports arrive with frame offsets
(symbolicate them with your dSYM), and there are no spans.
## How the pieces fit [#how-the-pieces-fit]
```text
your app ──(SDK or HTTP, ingest key)──▶ ingest.lyrelog.com ──▶ your project's events
│
you ──(browser, signed in)──▶ app.lyrelog.com ◀───────────────────────┘
```
Every project belongs to an [organization](/account/organizations). Its people see all its
projects, and its plan covers them all.
## Where to go next [#where-to-go-next]
## Pick your language [#pick-your-language]
# Limits
> Every limit Lyrelog applies, in one place.
Source: https://docs.lyrelog.com/limits
| What | Limit |
|---|---|
| A batch | 2,000 lines, 4 MiB sent and 4 MiB decompressed, 1 MiB a line |
| An event | `message` 2,048 bytes; `category` 64; ids 128; each `resource` key 64; `payload` 64 KiB; `attrs` 200 leaves, strings 1,024 bytes, string arrays 64 items, 4 levels deep |
| Ingest rate | 60,000 events a minute per project |
| One address, public key | A fiftieth of the plan's month per UTC day: Free 20,000, Pro 200,000, Business 4,000,000, Unlimited none. Verified events (server key, App Attest or Key Attestation) don't count. See [Verified events](/concepts/verification#the-daily-share-of-one-address) |
| Unknown keys | 30 a minute per address at ingest, 60 in 15 minutes at the read API |
| Timestamps | Kept as sent up to a day ahead; older than the retention or further ahead, stored at arrival |
| Free month | 1,000,000 events per organization, then `429` until the 1st (UTC) |
| Retention | Free 7 days, Pro 30, Business 1 year |
| Read API | 120 requests a minute per key; 4 queries at once per project; 15 seconds per query; ranges up to 400 days; 8 attribute filters; 100 values a filter; 1,000 events a page |
| Keys | 20 active per project. Keys don't expire: they work until revoked |
| Invitations | To an organization: 7 days, once. To Lyrelog: 14 days, once |
| A person's data export | 500,000 events or 512 MB |
| Dashboard queries | 4 at once per project (shared with its read and admin keys), 300 a minute per sign-in, 15 seconds each |
| Sessions in the dashboard | Signed out after 14 days unused, at most 30 days |
| CLI sign-in (`lyrelog login`) | Like a browser's, or kept 30 days, 90 days, 1 year or never, used or not. See [Sign in](/cli/login#the-session) |
| Access tokens (`lyr_tok_`) | Expire after 30 days, 90 days (the default), 1 year or never; unused doesn't end them |
| Recent sign-in | 10 minutes after signing in. See [the recent sign-in rule](/account/security#the-recent-sign-in-rule) |
| Sign-in and email links | Sign-in link by email: once, 1 hour. From Lyrelog's administrator: once, 24 hours. Confirming your email: 24 hours |
| Verified apps | Up to 10 Apple App IDs; up to 10 Android packages with 5 signing certificates each. Challenges: once, 5 minutes. Tokens: 24 hours, renewed by the SDK |
What each answer means and what to do: [HTTP API](/http-api#responses) and
[Read API](/read-api#limits-and-errors).
# Deleting a project
> A project and every event it received, gone for good.
Source: https://docs.lyrelog.com/projects/deleting
In **Project settings**, **Danger zone**, choose **Delete project**, and type the project's name
to confirm. Only an owner of the organization can. Deleting a project needs a recent sign-in
(within the last 10 minutes); otherwise Lyrelog asks you to sign in again first.
- Every event the project has received is deleted for good.
- Its keys and saved views go with it.
- Apps still sending to its keys are refused.
- **This can't be undone.**
Copies in Lyrelog's backups are gone within 30 days: they're kept for at most 30 days, encrypted,
on Lyrelog's servers in Germany and in Backblaze's data center in the Netherlands, and are only
used to restore the service after a fault.
Deleting a project doesn't change the organization, its plan or its people.
# A person's data
> Answer an access or erasure request from one of your users: find their events, download them, or delete them.
Source: https://docs.lyrelog.com/projects/privacy-requests
Your users can ask what you hold about them, or ask you to delete it. In Lyrelog, what you hold
about a person is the events your app sent with their `user_id`.
In **Project settings**, **A person's data** (the section's name uses the project's word for its
people, like "A player's data"):
### Find them [#find-them]
Type the user id exactly as your app sends it in `user_id`, and choose **Find**. You see how many
events they have in this project and the dates of the first and the last.
### Download their events [#download-their-events]
**Download them** gives a file with one JSON object per line: every event of that person, oldest
first, with all its fields. Anyone in the project can download, since they can read these events
in the dashboard anyway. Over 500,000 events or 512 MB, the file ends with a line
`{"truncated":true,"note":"..."}`: write to hello@lyrelog.com for the rest.
### Delete their events [#delete-their-events]
**Delete them** deletes every event with that user id, in every environment, for good. Only an
owner can. The events disappear from searches within a few minutes. Events your app sends later
with the same id still arrive, so stop sending them first if that's what the person asked.
Copies in Lyrelog's backups are gone within 30 days.
## What it doesn't cover [#what-it-doesnt-cover]
- Events sent without a `user_id` (before sign-in, for example) can't be found by it. If your app
sends something else that identifies the person, like an install id in an attribute, search for
it in the [explorer](/dashboard/explorer).
- It works one project at a time. If the person used several of your apps, repeat it in each.
- Your own copies, like an export you downloaded before, are yours to delete.
# Project settings
> A project's name, platforms, icon, the word for its people, environments, verified Apple and Android apps, retention and keys.
Source: https://docs.lyrelog.com/projects/settings
A project holds the events of one product: an app, and its website and backend if they have
them. Each project has a random public id, like `3f9a1c7e20bd`, that names it in dashboard
addresses and in the API. It says nothing about the project.
Open **Project settings** from the project's menu or the command menu. Everyone in the
project's [organization](/account/organizations) can see the settings; **only an owner can
change them**.
## Name [#name]
The name shown everywhere in Lyrelog.
## Platforms [#platforms]
Everything that sends events to this project. Add each one with **Add**: **iOS app**, **Mac
app**, **Android app**, **Website** or **Server**. One project can hold an app, its website and
its backend, and the dashboard can show each on its own (see
[Platforms](/concepts/platforms)). Remove a platform with its **×** button.
If events arrive from a platform that isn't set up yet, the section says so and offers to add it.
Each platform has its own details:
| Platform | Details |
|---|---|
| iOS app, Mac app | Its App Store listing. Search the App Store, or paste the app's link (`apps.apple.com/…/id1234567890`), and pick the **App Store country** to search in. Linking takes the app's name, link and icon from its listing. **Unlink** undoes it. |
| Android app | Its package (`com.example.app`) or its Google Play link. If the app is on Google Play, Lyrelog takes its name and icon. |
| Website | Its address (`example.com`). Lyrelog takes the site's icon if it has one it can use. |
| Server | Its language: Node, Python, Go, Java, Kotlin, Swift, Ruby, PHP, .NET, Rust, Elixir or Other. |
Lyrelog's server does the App Store, Google Play and website lookups. Your browser only loads the
images.
## Who uses it? [#who-uses-it]
**What to call them**: the word Lyrelog uses for your people on every page. Pick users, players,
customers, members, readers, listeners, students or clients, or **Another word** (singular and
plural). The default is users.
## Icon [#icon]
Shown beside the project everywhere in Lyrelog. Take it from one of the project's platforms
(**App Store**, **Google Play** or **Website**, when they have one) with **Use this one**, or
upload your own: drop an image or choose one, square, PNG, JPEG, WebP or GIF, up to 1 MB (no
SVG). **Remove** takes away an uploaded icon.
## Environments [#environments]
Development, test and production builds send to the same project, and each event says which one
it came from. **Default environment** is the one the dashboard opens on until someone picks
another in the top bar. It is `production` unless changed; it can also open on all
environments. The section explains how each SDK decides an event's environment (see
[Environments](/concepts/environments)).
## Verified events from your Apple apps [#verified-events-from-your-apple-apps]
Shown when the project has the iOS app platform. Add the **App ID** of each of your Apple apps,
up to 10: your Team ID, a dot and the bundle id, like `ABCDE12345.com.example.app`. The Team ID
is in your Apple Developer account, under **Membership**. With an App ID set, the
[Swift SDK](/sdks/swift#verified-events) (also under React Native and Flutter) proves with Apple's App Attest that
events come from your own app on a real iPhone, iPad or Apple Watch, and they arrive
[verified](/concepts/verification#apple-apps-app-attest). The app also needs the **App
Attest** capability. With no App ID, events from your apps arrive unverified. Remove one with its
**×** button.
Below, **Accept only verified events from the iOS app** (off by default, and only once an App ID
is set) holds back unverified events from the iOS app until they can prove themselves. Leave it off
while people still use a version without App Attest:
[what it does](/concepts/verification#accept-only-verified-events-from-the-ios-app).
## Verified events from your Android apps [#verified-events-from-your-android-apps]
Shown when the project has the Android app platform. Add each app's **package**, like
`com.example.app` (filled in from the Android app platform, when it has one), with the
**SHA-256 fingerprint** of a certificate it's signed with (as Play Console shows it,
`AB:CD:...`). Add the same package again for each certificate that signs builds
that send events: up to 5 per package, and up to 10 packages. With one set, the
[Android SDK](/sdks/android#verified-events) (also under React Native and Flutter) proves with Key Attestation that events come
from your own app on a real Android device, and they arrive
[verified](/concepts/verification#android-apps-key-attestation). With none, events from your
Android apps arrive unverified. Remove a certificate with its **×** button.
Below, **Accept only verified events from the Android app** (off by default, and only once a
package is set) holds back unverified events from the Android app until they can prove
themselves. Leave it off while people still use a version without Key Attestation:
[what it does](/concepts/verification#accept-only-verified-events-from-the-android-app).
## Keep events for [#retention]
7, 14, 30, 60, 90 or 180 days, or 1 year. Older events are deleted on their own. Lengthening
applies right away. Shortening asks first, because events older than the new limit are deleted
for good, within a few hours. See [Retention](/concepts/retention).
## Plan [#plan]
The organization's plan and its events this month. Every project in an organization shares the
plan, so their events count together. See [Plans and usage](/account/plans).
## People with access [#people-with-access]
Everyone in the project's organization sees all its projects. This section links to the
organization's page, where owners invite people and change their roles. See
[Organizations](/account/organizations).
## API keys [#api-keys]
**API keys**: the keys your apps send events with, and the ones scripts read them with. Create
one with a name and a scope (Send events, Send events from a server, Read events, Full access), copy it while it is shown,
and revoke it when it is no longer needed. Each key shows when it was last used. See
[Keys](/concepts/keys).
## Details [#details]
The project id, its slug, how long events are kept and when the project was created.
## A person's data [#a-persons-data]
Find one of your people by their user id, download their events, or delete them, to answer a
privacy request. The section's name uses the project's word ("A player's data"). See
[A person's data](/projects/privacy-requests).
## Danger zone [#danger-zone]
Only owners see it. [Delete the project](/projects/deleting).
# Quickstart
> Make a project, copy its ingest key, send a first event and find it in the dashboard.
Source: https://docs.lyrelog.com/quickstart
Lyrelog is a hosted service, in early access by invitation. Ask for access at
[lyrelog.com](https://lyrelog.com); the invitation link lets you make your account. The dashboard
lives at [app.lyrelog.com](https://app.lyrelog.com), and apps send their events to
`https://ingest.lyrelog.com`.
### Name your first project [#name-your-first-project]
After you make your account, the dashboard opens on **Welcome**. Give the project a name and say
what sends its events: an iOS or macOS app, a website, a Node, Python or Go service, or anything
else over HTTP. Your choice picks the snippet you see next and the project's platform.
Make one project per app. If the app also has a website and a backend, they can all send to the
same project (see [Platforms](/concepts/platforms)). Later projects come from **Projects** and
**New project**. Only an owner of the organization can make projects.
### Copy the ingest key [#copy-the-ingest-key]
Right after you make the project, Lyrelog shows its ingest key, `lyr_ing_...`, and the lines to
paste into your app. **Copy the key now:** only a hash of it is stored, so it can't be shown again.
If you lose it, make a new one on the project's **API keys** page.
The ingest key can only send events, never read them, so it is safe to ship inside an app. See
[Keys](/concepts/keys). A backend should send with a server key instead (**Send events from
a server**, on the **API keys** page), whose events are
[verified](/concepts/verification).
### Send a first event [#send-a-first-event]
The SDKs for [Swift](/sdks/swift), [Android](/sdks/android),
[React Native](/sdks/react-native), [Flutter](/sdks/flutter),
[JavaScript](/sdks/javascript), [Python](/sdks/python), [Go](/sdks/go) and the
[JVM](/sdks/jvm) can't be installed yet. For now, send your
first event with curl, or from any language over the [HTTP API](/http-api).
In a macOS or Linux terminal (it uses `uuidgen` and `date`), replace `lyr_ing_...` with your key
and run:
```bash
curl -X POST https://ingest.lyrelog.com/v1/events:batch \
-H "Authorization: Bearer lyr_ing_..." \
-H "Content-Type: application/x-ndjson" \
--data-binary "{\"event_id\":\"$(uuidgen | tr A-Z a-z)\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"message\":\"hello_lyrelog\",\"resource\":{\"environment\":\"production\"}}"
```
Every event needs a new UUID as `event_id` and the current time as `ts`. An event whose `ts` is
older than the project's retention, or more than a day ahead, isn't lost: it is stored at the time
it arrived, and the time it was sent goes in the attribute `_lyrelog_ts_clamped`. The answer says
how many lines were stored:
```json
{"accepted":1,"rejected":[]}
```
Anything else? See [No events arrive](/troubleshooting).
### See it arrive [#see-it-arrive]
The **Welcome** page waits for the first event and says so when it arrives. Open the project from
there: the **Events** page lists `hello_lyrelog`. Click it to see the whole event.
The dashboard shows one environment at a time and opens on the project's default,
`production`. The SDKs send `development` from a build you run in Xcode, from the simulator,
from a page on `localhost`, and from Node unless `NODE_ENV=production` is set, so your first
events from an SDK are under **development**: pick it, or **All environments**, in the top bar.
The curl above sets `"environment":"production"`; an event sent without
`resource.environment` is stored as `production` too. See
[Environments](/concepts/environments).
### Read it from a script (optional) [#read-it-from-a-script-optional]
On the project's **API keys** page, choose **New key**, set **What it can do** to **Read events**,
and copy the `lyr_read_...` key. Making a read key asks you to sign in again if your last sign-in
was more than 10 minutes ago. Keep it on a server: it reads every event of the project.
```bash
export LYRELOG_READ_KEY=lyr_read_...
curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "message=hello_lyrelog"
```
See the [Read API](/read-api).
## Next [#next]
- Learn what makes a good event: [Events](/concepts/events).
- Something not working: [No events arrive](/troubleshooting).
# Read API
> Query a project's events from a script with a read key.
Source: https://docs.lyrelog.com/read-api
The dashboard is one way to read events. The read API is the other: the same filters, as JSON,
for a script, a notebook, a scheduled job or an agent.
## Authentication [#authentication]
On the project's **API keys** page, choose **New key** and set **What it can do** to **Read events**. The key starts with
`lyr_read_` and is shown once. Send it as a bearer token to `https://app.lyrelog.com`. The examples below keep it in a shell
variable:
```bash
export LYRELOG_READ_KEY=lyr_read_...
curl -s https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY"
```
A read key sees every event of its project and nothing else. Keep it on a server: anyone who has
it can read your users' events. A **Full access** key reads too; an ingest key can't (`403`).
## List events [#list-events]
`GET /v1/events` answers the newest events first, 100 at a time, from the last 24 hours unless
you say otherwise.
| Parameter | Meaning |
|---|---|
| `from`, `to` | Unix milliseconds. Default: the last 24 hours. |
| `level` | One or more levels, comma separated: `error,critical` |
| `category`, `message` | The area and the event name. Several values with `\|`, `!` in front to exclude: `message=!http_request_served` |
| `user`, `session`, `install` | An id |
| `env`, `platform` | `production`, `ios`... Without them, every environment and platform. |
| `version`, `os`, `device`, `locale` | The app version, the OS version (`27.2.0`), the device model and the locale |
| `country` | Where the person is: the country of the address the events came from, else the region of the device's locale (`es_ES` is `ES`) |
| `verified` | How an event is [verified](/concepts/verification): `server` (sent with a server key), `app_attest` (sent by your Apple app, proven with App Attest), `none` (not verified) |
| `attr` | `path:value` on an attribute, or `path!:value` to exclude. Repeat it for several. |
| `q` | Text in the message or the area (any case), or an exact event, user, session or install id. Attributes aren't searched: use `attr`. |
| `limit` | 1 to 1000, default 100 |
| `order` | `asc` for oldest first |
| `cursor` | The `next_cursor` of the previous answer, for the next page |
`category`, `message`, `user`, `session`, `install`, `env`, `platform`, `version`, `os`,
`device`, `locale`, `country` and `verified` take several values separated by `|` ("is any of"), or a list
with `!` in front ("is not"): `os=26.4|27.2.0`, `platform=!web`. An `attr` value takes `|` too,
and is excluded with `!` after the path: `attr=plan!:free|trial`. Device models contain commas
(`iPhone18,1`), which is why the separator is `|`.
```bash
# Errors on iOS in production in the last hour
curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" \
--data-urlencode "platform=ios" \
--data-urlencode "env=production" \
--data-urlencode "from=$(( ($(date +%s) - 3600) * 1000 ))"
```
The answer is `{"events": [...], "next_cursor": "..."}`; `next_cursor` is `null` on the last page.
Each event has `event_id`, `ts` (Unix milliseconds), `level`, `category`, `message`, `user_id`,
`install_id`, `session_id` and `attrs`, plus the resource fields (`app_id`, `app_version`,
`app_build`, `os_name`, `os_version`, `device_model`, `locale`, `environment`, `platform`),
`country` and `verified_by`: `"server"` when the event came with a server key, `"app_attest"`
when your Apple app proved itself with App Attest, `""` when it isn't verified (see
[Verified events](/concepts/verification)). The list leaves the
payload out: ask for one event to get it.
### Every page [#every-page]
A cursor only continues the query it came from: send the same filters with it. Without `from`
and `to`, the window moves with the clock, so fix them when you read several pages. This reads
every error of the last 7 days, oldest first, 1000 at a time (it needs `jq`):
```bash
FROM=$(( ($(date +%s) - 7*86400) * 1000 )); TO=$(( $(date +%s) * 1000 )); CURSOR=""
while :; do
PAGE=$(curl -s -G https://app.lyrelog.com/v1/events \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "level=error,critical" --data-urlencode "order=asc" --data-urlencode "limit=1000" \
--data-urlencode "from=$FROM" --data-urlencode "to=$TO" ${CURSOR:+--data-urlencode "cursor=$CURSOR"})
echo "$PAGE" | jq -c '.events[]'
CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty'); [ -z "$CURSOR" ] && break
done
```
## One event [#one-event]
`GET /v1/events/{event_id}?ts={ts}` answers one event, with its whole payload, as `{"event": {...}}`.
Pass the `ts` (Unix milliseconds) the list gave you: events are stored by time, so the id alone
would mean searching all of them.
```bash
curl -s -G "https://app.lyrelog.com/v1/events/6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f" \
-H "Authorization: Bearer $LYRELOG_READ_KEY" \
--data-urlencode "ts=1794996000123"
```
```json
{"event":{"event_id":"6f1b2c3d-5a1e-4c1f-9e7a-0a1b2c3d4e5f","ts":1794996000123,"level":"error","category":"checkout","message":"payment_declined","user_id":"user-1","install_id":"","session_id":"2f9a...","app_id":"com.example.app","app_version":"2.0","app_build":"202611181200","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,1","locale":"es_ES","country":"ES","environment":"production","platform":"ios","verified_by":"","attrs":{"code":51},"payload":{"response":"..."}}}
```
A field the app didn't send is an empty string. `payload` is left out when the event has none.
## Limits and errors [#limits-and-errors]
| Status | Meaning |
|---|---|
| `400` | A parameter is wrong; the body says which. For example: `from` not before `to`, a range over 400 days, more than 8 `attr` filters, more than 100 values in one filter, an unknown level, `limit` outside 1 to 1000, a bad `cursor` |
| `401` | No key, or an unknown or revoked one |
| `403` | The key can't read (an ingest key) |
| `404` | No event with that id and `ts` |
| `429` | More than 120 requests a minute for this key (`Retry-After: 60`); the project already runs 4 queries at once, the dashboard and its keys together (`Retry-After: 2`); or more than 60 unknown keys from your address in 15 minutes |
| `500` | `{"error":"something went wrong on the server"}`. A query that takes over 15 seconds ends this way: narrow the range or add filters |
An error answers `{"error": "..."}`. Wait for `Retry-After` before trying again after a `429`.
Answers are never cached (`Cache-Control: no-store`). The API has no CORS headers on purpose: a
read key doesn't belong in a browser.
# Android
> Structured logs from your Android app, in Kotlin or Java. No dependencies beyond the Kotlin standard library.
Source: https://docs.lyrelog.com/sdks/android
The Android SDK needs Android 7.0 (API 24) or later. It is written in Kotlin, has no
dependencies beyond the Kotlin standard library (no OkHttp, coroutines or AndroidX), and every
function can be called from Java too.
Internal preview: this package isn't published yet. Until it is, Gradle can't fetch
`com.lyrelog:lyrelog-android`: it isn't on Maven Central, and the repository is private and has
no release yet.
## Install [#install]
From Maven Central, in your app module's `build.gradle.kts`:
```kotlin
dependencies {
implementation("com.lyrelog:lyrelog-android:0.1.0")
}
```
The library adds the `INTERNET` permission to your app's manifest.
## Start [#start]
Start once, as early as possible, in your `Application`'s `onCreate`. A second call while it
runs is ignored. Events logged before `start` are ignored too, but `setUser` and `setConsent`
called before `start` are kept and applied when it runs.
```kotlin
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...", // ingest-only: it can append events, never read them
))
}
}
```
Name the class in the manifest (``) if your app doesn't
have an `Application` yet.
Events go to `https://ingest.lyrelog.com`. Pass `endpoint` only to send them somewhere else. It
is the base URL (a pasted `.../v1/events:batch` path is stripped) and must be `https`; plain
`http` works only for `localhost`, `127.0.0.1` or `::1`, and on the emulator for `10.0.2.2` (see
[In development and tests](#in-development-and-tests)). With any other endpoint nothing is sent
and the events stay on the device.
## Log events [#log-events]
One function per level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`, or
`log(level, message, ...)` with a `Level`.
```kotlin
Lyrelog.info("checkout_done", attrs = mapOf("items" to 3, "latency_ms" to ms))
Lyrelog.error("payment_declined", category = "checkout",
attrs = mapOf("code" to 51), payload = mapOf("response" to raw))
```
Attributes are a `Map`: strings, numbers, booleans, `null`, lists (their items
sent as strings) and nested maps up to 4 levels. The payload is any map, list or value, for the
detail you only read when you open one event.
## Loggers for each area [#loggers-for-each-area]
A logger stamps its `category` on every event, like an Android log tag. It has every level, plus
`log` and `captureError`. It is cheap to make and keep, and logs into whatever SDK is running
when it is called.
```kotlin
val sync = Lyrelog.logger("sync")
sync.warning("sync_conflict", mapOf("records" to 2))
```
## Users [#users]
```kotlin
Lyrelog.setUser(playerId) // attached to every following event
Lyrelog.setUser(null) // on sign-out
```
`Lyrelog.sessionId` gives the current session id, for example to show in a support screen.
The user id isn't saved between launches: call `setUser` again on each launch, once you know who
the person is.
## Screens [#screens]
Say where the person is. Lyrelog logs `screen_viewed` (area `navigation`) with the screen before
and the seconds spent on it, and tags every following event with a `screen` attribute.
```kotlin
override fun onResume() {
super.onResume()
Lyrelog.screen("Settings")
}
```
In Compose, call it from a `LaunchedEffect` when a destination is shown. The event carries
`screen`, `previous_screen` and `seconds_on_previous`. Calling `screen` again with the same name
logs nothing. `screen` takes extra `attrs` for the `screen_viewed` event. Turn the tagging off
with `attachScreen = false`.
`automaticScreens = true` does it for every Activity that comes to the front, named by its class
(`SettingsActivity`). It is off by default: Compose and fragment apps have many screens in one
Activity, and a name you choose reads better on the dashboard.
## Errors you catch [#errors-you-catch]
```kotlin
try {
store.purchase(product)
} catch (e: IOException) {
Lyrelog.captureError(e, category = "store")
}
```
It sends the `exception` event every SDK sends: level `error`, the attributes `error_type` (the
class name) and `error_message`, and a payload with the description, up to 60 frames, the causes
(up to 8, 20 frames each) and suppressed exceptions. `attrs` adds your own; `level` changes the
level. Each logger has `captureError` too.
Frames are as the VM reports them. When the app is minified with R8, run `retrace` with the
build's mapping file to get the original names.
## Crashes [#crashes]
An uncaught exception is written to disk on the spot, on the thread that is dying, together with
any event still on its way to the disk. Then it is handed to the handler that was there before
(the system's crash dialog, or another crash reporter that installed one first). Nothing is sent
then: the process is about to end.
The next launch sends it, at the time it happened and in the session it ended, in the
`diagnostics` area, like the Swift SDK's crash reports, so both platforms' crashes sit together
in the dashboard:
| Event | Level | What it carries |
|---|---|---|
| `app_crashed` | critical | `error_type`, `error_message`, `handled: false`, `mechanism: uncaught_exception`, and a payload with the thread, the frames, the causes and suppressed exceptions |
It's on by default; turn it off with `captureCrashes = false`. Native crashes and ANRs aren't
reported.
## Environments and platform [#environments-and-platform]
When it starts, the SDK picks the environment: `development` when the app is debuggable
(`android:debuggable`, every debug build), `production` otherwise.
Your own debug builds send `development`, while the dashboard opens on `production`: pick
**development** in the top bar to see them.
The platform is `android`. Override either in the configuration:
```kotlin
Configuration(
apiKey = key,
environment = if (BuildConfig.FLAVOR == "beta") "beta" else null, // null = detected
platform = null,
)
```
Any name works: lowercase letters, digits, `-` and `_`, up to 32. Other text is turned into a
valid name (`Staging EU` becomes `staging-eu`).
## Consent [#consent]
```kotlin
Lyrelog.start(this, Configuration(apiKey = key, consent = Consent.PENDING))
// later, when the person chooses:
Lyrelog.setConsent(Consent.GRANTED) // sends, including what was kept while pending
Lyrelog.setConsent(Consent.DENIED) // deletes everything and stops recording
```
`PENDING` keeps events on the device without sending them. Nothing is uploaded unless consent
is granted, including what an earlier launch left. Starting with `Consent.DENIED` deletes anything
still queued from an earlier launch and the install id, and records nothing. A `setConsent`
before `start` wins over `Configuration.consent`.
Consent isn't saved between launches: store the person's choice yourself and pass it to
`start` each time.
## A complete app [#a-complete-app]
Start with the stored consent, set the person when they sign in and tag screens:
```kotlin
import android.app.Application
import com.lyrelog.Configuration
import com.lyrelog.Consent
import com.lyrelog.Lyrelog
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
val prefs = getSharedPreferences("settings", MODE_PRIVATE)
val consent = when (prefs.getString("diagnostics", null)) {
"granted" -> Consent.GRANTED
"denied" -> Consent.DENIED
else -> Consent.PENDING
}
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", consent = consent))
}
}
class HomeActivity : AppCompatActivity() {
override fun onResume() {
super.onResume()
Lyrelog.screen("Home")
}
private fun signedIn(account: Account) {
Lyrelog.setUser(account.id)
Lyrelog.info("signed_in", category = "auth")
}
}
fun choose(context: Context, allowed: Boolean) {
context.getSharedPreferences("settings", Context.MODE_PRIVATE).edit()
.putString("diagnostics", if (allowed) "granted" else "denied").apply()
Lyrelog.setConsent(if (allowed) Consent.GRANTED else Consent.DENIED)
}
```
## Flush and stop [#flush-and-stop]
Going to the background already sends (when the last Activity stops; a rotation doesn't count),
so you rarely need to.
```kotlin
Lyrelog.flushInBackground() // send now, without waiting
Lyrelog.flush() // write everything to disk and send, waiting up to 5 seconds
Lyrelog.stop() // send what's queued (up to 2 seconds), then stop
Lyrelog.stopNow() // stop at once; what was logged goes with the next launch
```
`flush` and `stop` block, so never call them on the main thread. `flush` returns `true` when it
finished in time, and respects a `Retry-After` the server asked for: it doesn't send sooner.
After `stop`, `start` can be called again.
## In development and tests [#in-development-and-tests]
Don't call `Lyrelog.start` in unit tests: anything logged before `start` is ignored, so the rest
of your code runs unchanged. `mirrorToLogcat = true` also prints every event to logcat (tag
`Lyrelog`) while you work.
Debug builds send environment `development`. To send from the emulator to an endpoint running on
your computer, use `http://10.0.2.2` and its port as the endpoint (`10.0.2.2` is your computer,
as the emulator sees it), in the debug build only:
- **Allow plain http to `10.0.2.2`.** Android blocks it unless the app allows it: add a network
security config to the debug build that permits cleartext for that one address.
- **On Android 17, an app targeting API 37 also needs `ACCESS_LOCAL_NETWORK`** to reach a
private address like `10.0.2.2`; without it the connection just times out. Declare the
permission in the debug manifest (`src/debug/AndroidManifest.xml`) and grant it:
`adb shell pm grant android.permission.ACCESS_LOCAL_NETWORK`.
This is only for local development. The hosted ingest is a public `https` address and needs
neither.
## Verified events [#verified-events]
A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).
An Android app's events are verified with
[Key Attestation](/concepts/verification#android-apps-key-attestation): the phone's secure
hardware proves that they come from your own app, signed with your certificate, on a real device
that hasn't been rooted or unlocked. Lyrelog checks it on its own servers; no Google account,
Play Integrity or Google Cloud project is involved.
It is on by default (`attest` in `Configuration`); set it up in the project:
1. In [Project settings](/projects/settings#verified-events-from-your-android-apps), under
**Verified events from your Android apps**, add your package and the SHA-256 fingerprint of
each certificate that signs builds that send events: Play's app signing key (Play Console,
**Test and release**, **App integrity**) and, for builds you sign yourself, the one
`./gradlew signingReport` shows.
2. That's all in the app. To turn it off:
```kotlin
Lyrelog.start(this, Configuration(apiKey = "lyr_ing_...", attest = false))
```
Once per install the SDK makes a key in the phone's secure hardware (StrongBox or the trusted
execution environment) and has the device attest it; from then on its batches carry a token and
arrive verified (`verified_by` is `key_attestation`). The token lasts 24 hours and is renewed in
the background before it ends. Sending never waits for this: until the app has a token, and
whenever anything fails, events are sent unverified.
- Emulators never verify, and the SDK doesn't try there.
- Until the project has an Android app set up, or when the key is refused or the device can't
attest, the SDK turns attestation off for that launch and says so once in logcat.
- A device the server refuses (a rooted phone, an unlocked bootloader, a certificate the project
doesn't list) tries again a day later.
- Denying [consent](#consent) deletes the attested key and its record
(`noBackupFilesDir/lyrelog/attest.json`).
Until it's set up, events arrive unverified and count toward the
[daily share of one address](/concepts/verification#the-daily-share-of-one-address). Before
making the project accept only verified events from `android`, check in the explorer that your
real users' events arrive verified: events from older versions, emulators and refused devices
would be held back with a `425`.
Events your own servers send with a server key, `lyr_srv_...`, are verified. Never put a server
key in an app: anything shipped in an APK can be read.
To check, open the [explorer](/dashboard/explorer): an opened event says it under
**Context**, in its **Sender** line: **Verified, Key Attestation** or **Not verified, public key**.
See [Verified events](/concepts/verification) for who verifies what and the daily share.
## From Java [#from-java]
Every function on `Lyrelog` is static from Java, with overloads for the optional arguments:
```java
Lyrelog.start(this, new Configuration("lyr_ing_..."));
Lyrelog.info("checkout_done");
Lyrelog.captureError(e, "store");
```
`Configuration` and a logger's functions have overloads too, so trailing arguments can be left
out (`logger.warning("sync_conflict")`, `logger.warning("sync_conflict", attrs)`).
## Configuration [#configuration]
| Option | Default | Meaning |
|---|---|---|
| `apiKey` | required | The project's ingest key |
| `endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is stripped. `https` only, `http` only for localhost and the emulator's `10.0.2.2` |
| `consent` | `Consent.GRANTED` | `PENDING`, `GRANTED` or `DENIED` |
| `minimumLevel` | `Level.DEBUG` | Events below it never reach the disk |
| `flushIntervalMillis` | 15 s | How often the uploader runs while an Activity is started |
| `maxBatchBytes` | 512 KiB | A batch closes at whichever limit comes first (kept within 4 MiB) |
| `maxBatchEvents` | 500 | At most 2,000 |
| `maxDiskBytes` | 20 MB | Cap on the queue on disk, oldest first |
| `maxEventAgeMillis` | 7 days | Older queued events are dropped |
| `sessionTimeoutMillis` | 30 min | Idle time that starts a new session |
| `environment` | detected | Any valid name, or `null` |
| `platform` | `android` | Any valid name, or `null` |
| `appVersion` | the app's `versionName` | Sent as `resource.app_version` |
| `redactedKeys` | `null`: `DEFAULT_REDACTED_KEYS` | Key names to redact; your list replaces the defaults, an empty list turns it off |
| `captureCrashes` | `true` | Record uncaught exceptions, sent on the next launch |
| `attachScreen` | `true` | Tag events with the current screen |
| `automaticScreens` | `false` | Log `screen_viewed` for each Activity, named by its class |
| `attest` | `true` | Prove the app with [Key Attestation](#verified-events) so its events arrive verified, once the project lists its package and certificate |
| `mirrorToLogcat` | `false` | Also print every event to logcat (tag `Lyrelog`) |
| `storageDirectory` | `noBackupFilesDir/lyrelog` | Where the queue lives |
## Delivery and limits [#delivery-and-limits]
| | |
|---|---|
| Never blocks | Logging copies the event and returns; one background writer puts it on disk and never waits on the network. |
| Survives kills and offline | A queue in `noBackupFilesDir/lyrelog`, capped at 20 MB and 7 days. What reached the disk survives a crash, a kill or days offline; events still on their way to the writer (milliseconds) are written by the crash handler, or lost if the process is killed outright. The folder is never in a backup, so a restored phone doesn't resend another device's events. |
| When it sends | Every 15 s while an Activity is started, and once when the app goes to the background. In the background nothing runs on a timer: what's left goes on the next launch or the next time the app comes to the front. |
| Batches | Up to 500 events or 512 KiB per request, gzipped. An event over 1 MiB once encoded is dropped and counted. |
| Retries | 1 s doubling to 5 min, with full jitter, honoring `Retry-After`. Any other 4xx drops the batch, a 3xx (a redirect, never followed) drops it, and a revoked key (`401`, `403`) stops sending until the next launch and keeps the events. A batch the server keeps failing while others go through goes to the back, then is dropped. |
| Monthly quota | When a Free organization has used its month's events, the server answers `429`. Events stay in the queue on disk and go out once the server takes them again, within the 20 MB and 7 day caps. The SDK logs one warning to logcat, and again only after a batch has been accepted in between. |
| Drops are visible | Events lost to the caps become one `lyrelog_events_dropped` warning (area `lyrelog`) with the count. |
| Its own problems | A wrong endpoint, a `404`, rejected lines or an endpoint that doesn't answer go once per launch to logcat, tag `Lyrelog`, at debug level. |
| Context | App id (the package name), version name, version code, `android`, the Android version, the device (`Google Pixel 9`), locale, environment, platform `android`, session id (new after 30 min idle) and install id. |
| Secrets | Values under keys whose name is or ends with `authorization`, `cookie`, `password`, `token`, `secret`, `apikey` and the rest of the [shared list](/sdks#what-every-sdk-does-for-you) become `"[redacted]"`, at any depth, before anything is cut. |
| Limits | Long strings cut on a character boundary, extra attributes counted in `lyrelog_dropped_attrs`, payloads over 64 KiB summarized as `{"lyrelog_truncated": true, "bytes": N, "preview": "..."}`. |
Change the list with `redactedKeys`: your list replaces the defaults, and an empty list turns
redaction off. To add to it:
```kotlin
Lyrelog.start(this, Configuration(
apiKey = "lyr_ing_...",
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "pin",
))
```
## Play data safety [#play-data-safety]
For the Play Console's data safety form, declare what your app sends through Lyrelog:
- **App info and performance:** Crash logs, Diagnostics (App functionality, and Analytics if
you use it that way). Collected, not shared.
- **Device or other IDs:** the install id, a random UUID that isn't the advertising id, isn't
backed up and is deleted on a denial. Not linked to the person unless you also call `setUser`.
- **App activity > App interactions:** if you log screens (`screen_viewed`) or taps.
- Anything else your `attrs` or `payload` carry (emails, purchases...), under its own category.
Data is encrypted in transit (`https`). The server adds the country of the sending address; the
address itself isn't stored.
# Flutter
> Structured logs from your Flutter app on iOS and Android, over the native Lyrelog SDKs.
Source: https://docs.lyrelog.com/sdks/flutter
The Flutter SDK is the Dart package `lyrelog`, a plugin for iOS 16 and Android 7.0 (API 24) or
later, built with Flutter 3.50. It is a thin Dart layer over the native SDKs, the
[Swift SDK](/sdks/swift) on iOS and the [Android SDK](/sdks/android) on Android, so
the queue on disk, native crashes, sending in the background, sessions, consent and verified
events work as they do there. On top, it reports Dart errors nobody caught and names screens
from your navigator.
Internal preview: this package isn't published yet. Until it is, `flutter pub add lyrelog`
finds nothing: it isn't on pub.dev, and the repository is private and has no release yet.
## Install [#install]
```bash
flutter pub add lyrelog
```
Or in `pubspec.yaml`:
```yaml
dependencies:
lyrelog: ^0.1.0
```
### iOS setup [#ios-setup]
- The plugin is a Swift package, so your app builds it with Swift Package Manager, which
Flutter uses by default. There is no CocoaPods version.
- Set the app's minimum to **iOS 16**: in Xcode, the Runner target, **General**, **Minimum
Deployments** (`IPHONEOS_DEPLOYMENT_TARGET = 16.0`). Flutter's default is lower, and the build
stops with a message saying so.
### Android setup [#android-setup]
- Flutter's defaults work: compileSdk 36 and Kotlin 2.2 or newer. `minSdk` can stay at 24.
The library adds the `INTERNET` permission to your app's manifest.
## Start [#start]
Start once, as early as possible: in `main`, before `runApp`. A second call while it runs is
ignored. `start` calls `WidgetsFlutterBinding.ensureInitialized()` itself, so it can come first,
and nothing needs to wait for it: what you log after `start` reaches the native SDK after it.
Events logged before `start` are ignored, but `setUser` and `setConsent` called before `start`
are kept and applied when it runs.
```dart
import 'package:flutter/widgets.dart';
import 'package:lyrelog/lyrelog.dart';
void main() {
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...', // ingest-only: it can append events, never read them
));
runApp(const MyApp());
}
```
Events go to `https://ingest.lyrelog.com`. Pass `endpoint` only to send them somewhere else. It
is the base URL (a pasted `.../v1/events:batch` path is stripped) and must be `https`; plain
`http` works only for `localhost`, `127.0.0.1` or `::1`, and on the Android emulator for
`10.0.2.2` (see [In development and tests](#in-development-and-tests)). With any other endpoint
nothing is sent and the events stay on the device.
## Log events [#log-events]
One function per level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`, or
`log(level, message, ...)` with a `LogLevel`.
```dart
Lyrelog.info('checkout_done', attrs: {'items': 3, 'latency_ms': ms});
Lyrelog.error('payment_declined', category: 'checkout',
attrs: {'code': 51}, payload: {'response': raw});
```
Attributes are a `Map`: strings, numbers, booleans, `null`, lists and nested
maps up to 4 levels. A `DateTime` is sent as ISO 8601 text, a `Duration` as milliseconds, an enum
as its name, and anything else as its `toString()`. The payload is any value of those kinds, for
the detail you only read when you open one event.
## Loggers for each area [#loggers-for-each-area]
A logger stamps its `category` on every event, like a log tag. It has every level, plus `log`
and `captureError`. It is cheap to make and keep, and logs into whatever SDK is running when it
is called.
```dart
final sync = Lyrelog.logger('sync');
sync.warning('sync_conflict', attrs: {'records': 2});
```
## Users [#users]
```dart
Lyrelog.setUser(account.id); // attached to every following event
Lyrelog.setUser(null); // on sign-out
```
`await Lyrelog.sessionId()` gives the current session id, for example to show in a support
screen.
The user id isn't saved between launches: call `setUser` again on each launch, once you know who
the person is.
## Screens [#screens]
Say where the person is. Lyrelog logs `screen_viewed` (area `navigation`) with the screen before
and the seconds spent on it, and tags every following event with a `screen` attribute.
Add `LyrelogNavigatorObserver` to your app's navigator, and every page route that comes to the
top is a screen, named by its route name:
```dart
MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/settings': (_) => const SettingsPage(),
},
)
```
It works with any `Navigator`, so also with a router that takes observers (with `go_router`,
`GoRouter(observers: [LyrelogNavigatorObserver()], ...)`). Going back to a page logs it again,
since it is the screen once more. Dialogs, bottom sheets and menus don't change the screen, and
routes without a name are skipped. Change either:
```dart
LyrelogNavigatorObserver(
nameExtractor: (settings) => settings.name?.replaceFirst('/', ''), // null or '' skips the route
routeFilter: (route) => route is PageRoute, // which routes are screens
)
```
Or call it yourself:
```dart
Lyrelog.screen('Settings');
```
The event carries `screen`, `previous_screen` and `seconds_on_previous`. Calling `screen` again
with the same name logs nothing. `screen` takes extra `attrs` for the `screen_viewed` event. Turn
the tagging off with `attachScreen: false`.
## Errors you catch [#errors-you-catch]
```dart
try {
await store.purchase(product);
} catch (e, s) {
Lyrelog.captureError(e, stackTrace: s, category: 'store');
}
```
It sends the `exception` event every SDK sends: level `error`, the attributes `error_type` (the
runtime type) and `error_message` (its `toString()`), and a payload with the description and up
to 60 frames of the stack. Without a `stackTrace`, the frames are an `Error`'s own stack, if it
has one. `attrs` adds your own; `level` changes the level. Each logger has `captureError` too.
## Errors and crashes [#errors-and-crashes]
### Dart errors nobody catches [#dart-errors-nobody-catches]
`start` reports them on its own (`captureErrors`, on by default), as `exception` events with
`handled: false` and a `mechanism` that says where Flutter handed them over:
| `mechanism` | From | The payload also has |
|---|---|---|
| `flutter_error` | `FlutterError.onError`: errors while building, laying out or painting widgets, and in gesture callbacks | `library` (`widgets library`) and `context` (`building MyWidget`) |
| `platform_dispatcher` | `PlatformDispatcher.instance.onError`: errors in async code, timers and futures nobody awaited | |
The handlers that were there before keep running, after Lyrelog's, and
`PlatformDispatcher.onError` answers what the earlier one answered (without one, Flutter still
prints the error). If you set handlers of your own, set them before `start`, or call
`captureError` from them.
At most 10 of these are sent a minute, and the same error (its type, message and top frame) only
once every 10 seconds, so a layout error that repeats on every frame sends one event. Errors that
Flutter marks as silent, which it doesn't report in release builds either (an image that failed
to load, for example), are left out.
A Dart error doesn't end a Flutter app, so these are `exception` events, never `app_crashed`.
If your app runs in a zone of its own, report the zone's errors the same way:
```dart
runZonedGuarded(() => runApp(const MyApp()), (error, stack) {
Lyrelog.captureError(error, stackTrace: stack, handled: false, mechanism: 'zone');
});
```
### Native crashes [#native-crashes]
Crashes of the app itself come from the native SDKs (`captureNativeCrashes`, on by default).
They are sent on the next launch, at the time they happened, in the `diagnostics` area:
| Platform | Events | From |
|---|---|---|
| iOS | `app_crashed` (critical), `app_hung` (error), `cpu_overuse`, `disk_write_overuse`, `slow_launch` (warnings) | MetricKit, as on the [Swift page](/sdks/swift#crashes-and-hangs) |
| Android | `app_crashed` (critical) with `handled: false` and `mechanism: uncaught_exception` | Uncaught JVM exceptions, as on the [Android page](/sdks/android#crashes) |
On Android, native (C or C++) crashes and ANRs aren't reported.
### Obfuscated builds [#obfuscated-builds]
With `flutter build --obfuscate --split-debug-info=`, type names in `error_type` and the
frames are obfuscated. Keep the symbols the build writes and run `flutter symbolize` with them
on the frames to read them.
## Environments and platform [#environments-and-platform]
The native SDK picks the environment when it starts:
- **iOS**: `development` for a debug build, any build on the simulator, or a build with an
embedded provisioning profile (development and ad hoc signing); `testflight` for a TestFlight
build; `production` otherwise. Then StoreKit's answer, as on the
[Swift page](/sdks/swift#environments-and-platform).
- **Android**: `development` when the app is debuggable (every debug build), `production`
otherwise.
Your own `flutter run` builds send `development`, while the dashboard opens on `production`:
pick **development** in the top bar to see them.
The platform is the OS, `ios` or `android`, so one project holds both and the dashboard can
filter by each. Override either in the configuration:
```dart
LyrelogConfiguration(
apiKey: key,
environment: isInternalTester ? 'internal' : null, // null = detected
platform: null,
)
```
Any name works: lowercase letters, digits, `-` and `_`, up to 32. Other text is turned into a
valid name (`Staging EU` becomes `staging-eu`).
## Consent [#consent]
```dart
Lyrelog.start(LyrelogConfiguration(apiKey: key, consent: Consent.pending));
// later, when the person chooses:
Lyrelog.setConsent(Consent.granted); // sends, including what was kept while pending
Lyrelog.setConsent(Consent.denied); // deletes everything and stops recording
```
`Consent.pending` keeps events on the device without sending them. Nothing is uploaded unless
consent is granted, including what an earlier launch left. Starting with `Consent.denied`
deletes anything still queued from an earlier launch and the install id, and records nothing. A
`setConsent` before `start` wins over the configuration's `consent`.
Consent isn't saved between launches: store the person's choice yourself and pass it to
`start` each time.
## A complete app [#a-complete-app]
Start with the stored consent, set the person when they sign in and name screens from the
navigator:
```dart
import 'package:flutter/material.dart';
import 'package:lyrelog/lyrelog.dart';
import 'package:shared_preferences/shared_preferences.dart';
Future main() async {
WidgetsFlutterBinding.ensureInitialized();
final prefs = await SharedPreferences.getInstance();
final consent = switch (prefs.getString('diagnostics')) {
'granted' => Consent.granted,
'denied' => Consent.denied,
_ => Consent.pending,
};
Lyrelog.start(LyrelogConfiguration(apiKey: 'lyr_ing_...', consent: consent));
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) => MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/sign-in': (_) => SignInPage(onSignedIn: signedIn),
},
);
}
void signedIn(Account account) {
Lyrelog.setUser(account.id);
Lyrelog.info('signed_in', category: 'auth');
}
Future choose(bool allowed) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('diagnostics', allowed ? 'granted' : 'denied');
Lyrelog.setConsent(allowed ? Consent.granted : Consent.denied);
}
```
## Flush and stop [#flush-and-stop]
Going to the background already sends: on iOS inside a background task, on Android when the
app's Activity stops. So you rarely need to.
```dart
await Lyrelog.flush(); // write everything to disk and send, waiting up to 5 seconds
await Lyrelog.stop(); // send what's queued (up to 2 seconds), then stop
```
`flush` returns `true` when it finished in time (`timeout:` changes the wait), and respects a
`Retry-After` the server asked for: it doesn't send sooner. After `stop`, `start` can be called
again.
## In development and tests [#in-development-and-tests]
In widget and unit tests, don't call `Lyrelog.start`: anything logged before `start` is ignored,
so the rest of your code runs unchanged. On a platform the plugin doesn't support (web,
desktop), every call does nothing and never throws.
`mirrorToConsole: true` also prints every event to the native log while you work: Xcode's
console on iOS, logcat (tag `Lyrelog`) on Android.
Debug builds send environment `development`. To send to an endpoint running on your computer:
- **iOS simulator**: use `http://127.0.0.1` and its port. The simulator shares your computer's
network, and no App Transport Security exception is needed for it.
- **Android emulator**: use `http://10.0.2.2` and its port (`10.0.2.2` is your computer, as the
emulator sees it), in the debug build only:
- **Allow plain http to `10.0.2.2`.** Android blocks it unless the app allows it: add a
network security config to the debug build (`android/app/src/debug`) that permits cleartext
for that one address.
- **On Android 17, an app targeting API 37 also needs `ACCESS_LOCAL_NETWORK`** to reach a
private address like `10.0.2.2`; without it the connection just times out. Declare the
permission in the debug manifest (`android/app/src/debug/AndroidManifest.xml`) and grant it:
`adb shell pm grant android.permission.ACCESS_LOCAL_NETWORK`.
Keep the key out of your sources with `--dart-define-from-file`, for example
`flutter run --dart-define-from-file=lyrelog.local.json` and
`String.fromEnvironment('LYRELOG_KEY')`, with that file ignored by git.
This is only for local development. The hosted ingest is a public `https` address and needs
none of this.
## Verified events [#verified-events]
A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).
The native SDKs verify the app on real devices (`attest`, on by default), and nothing changes in
your Dart code. Set up each platform the app ships on:
- **iOS, with Apple's App Attest** (`verified_by` is `app_attest`):
- Add the **App Attest** capability to the Runner target in Xcode (Signing & Capabilities),
the entitlement `com.apple.developer.devicecheck.appattest-environment`. Set it to
`production` for App Store and TestFlight builds; without it Apple uses the development
environment.
- Add your **App ID**, the Team ID, a dot and the bundle id (`ABCDE12345.com.example.app`), in
[Project settings](/projects/settings#verified-events-from-your-apple-apps), under
**Verified events from your Apple apps**.
- **Android, with [Key Attestation](/concepts/verification#android-apps-key-attestation)**
(`verified_by` is `key_attestation`): in
[Project settings](/projects/settings#verified-events-from-your-android-apps), under
**Verified events from your Android apps**, add your package and the SHA-256 fingerprint of
each certificate that signs builds that send events: Play's app signing key (Play Console,
**Test and release**, **App integrity**) and, for builds you sign yourself, the one
`./gradlew signingReport` shows (run it in your app's `android` folder).
To turn it off on both:
```dart
Lyrelog.start(const LyrelogConfiguration(apiKey: 'lyr_ing_...', attest: false));
```
Sending never waits for it: until the app has a token, and whenever anything fails, events are
sent unverified. Until a platform is set up in the project, the SDK stops trying for that launch.
- The iOS simulator and Android emulators never verify.
- A device the server refuses (a rooted phone, an unlocked bootloader, a certificate the
project doesn't list) sends unverified events; Android tries again a day later.
- Denying [consent](#consent) deletes the attested key's record on both platforms.
Before making the project accept only verified events from `ios` or `android`, check in the
explorer that your real users' events arrive verified: events from older versions, simulators,
emulators and refused devices would be held back with a `425`. Never put a server key
(`lyr_srv_...`) in an app: anything shipped in an app can be read.
To check, open the [explorer](/dashboard/explorer): an opened event says it under
**Context**, in its **Sender** line: **Verified, App Attest**, **Verified, Key Attestation** or
**Not verified, public key**.
## Configuration [#configuration]
| Option | Default | Meaning |
|---|---|---|
| `apiKey` | required | The project's ingest key |
| `endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is stripped. `https` only, `http` only for localhost and the Android emulator's `10.0.2.2` |
| `consent` | `Consent.granted` | `pending`, `granted` or `denied` |
| `minimumLevel` | `LogLevel.debug` | Events below it are dropped before they reach the device's queue |
| `flushInterval` | 15 s | How often the uploader runs in the foreground |
| `maxBatchBytes` | 512 KiB | A batch closes at whichever limit comes first (kept within 4 MiB) |
| `maxBatchEvents` | 500 | At most 2,000 |
| `maxDiskBytes` | 20 MB | Cap on the queue on disk, oldest first |
| `maxEventAge` | 7 days | Older queued events are dropped |
| `sessionTimeout` | 30 min | Idle time that starts a new session |
| `environment` | detected | Any valid name, or `null` |
| `platform` | the OS | Any valid name, or `null` |
| `redactedKeys` | `null`: `defaultRedactedKeys` | Key names to redact; your list replaces the defaults, an empty list turns it off |
| `captureErrors` | `true` | Report Dart errors nobody caught |
| `captureNativeCrashes` | `true` | iOS: MetricKit crashes, hangs and overuse reports. Android: uncaught JVM exceptions. Sent on the next launch |
| `attachScreen` | `true` | Tag events with the current screen |
| `attest` | `true` | Verify events with [App Attest or Key Attestation](#verified-events) once the project is set up |
| `mirrorToConsole` | `false` | Also print every event to the native log (Xcode's console, logcat) |
| `pauseUploadsInLowPowerMode` | `true` | iOS only: periodic uploads pause; going to the background still sends |
## Delivery and limits [#delivery-and-limits]
Delivery is the native SDK's, the same as in a Swift or Kotlin app:
| | iOS | Android |
|---|---|---|
| Never blocks | A call hands the event to the native SDK and returns; one background writer puts it on disk and never waits on the network. | The same. |
| Survives kills and offline | A queue in Library/Caches, capped at 20 MB and 7 days. The system may purge Caches when the device is short of space, and the waiting events go with it. | A queue in `noBackupFilesDir/lyrelog`, capped at 20 MB and 7 days, never in a backup, so a restored phone doesn't resend another device's events. |
| When it sends | Every 15 s in the foreground (paused in Low Power Mode), and when the app goes to the background, inside a background task. | Every 15 s while the app's Activity is started, and when it goes to the background. In the background nothing runs on a timer: what's left goes on the next launch or the next time the app comes to the front. |
| Batches | Up to 500 events or 512 KiB per request, gzipped. An event over 1 MiB once encoded is dropped and counted. | The same. |
| Retries | 1 s doubling to 5 min, with full jitter, honoring `Retry-After`. Any other 4xx drops the batch, a 3xx (a redirect, never followed) drops it, and a revoked key (`401`, `403`) stops sending until the next launch and keeps the events. A batch the server keeps failing while others go through goes to the back, then is dropped. | The same. |
| Monthly quota | When a Free organization has used its month's events, the server answers `429`. Events stay in the queue on disk and go out once the server takes them again, within the 20 MB and 7 day caps. One warning in the unified log (subsystem `com.lyrelog.sdk`). | The same, the warning in logcat (tag `Lyrelog`). |
| Drops are visible | Events lost to the caps become one `lyrelog_events_dropped` warning (area `lyrelog`) with the count. | The same. |
| Its own problems | A wrong endpoint, a refused key or rejected lines go once per launch to the unified log, subsystem `com.lyrelog.sdk`, at debug level. | The same in logcat, tag `Lyrelog`, at debug level. |
| Context | App id, version, build, OS, device model (`iPhone18,1`), locale, platform `ios`, session id (new after 30 min idle) and install id. `sdk` is `lyrelog-flutter/0.1.0 lyrelog-swift/0.1.0`. | App id (the package name), version name, version code, the Android version, the device (`Google Pixel 9`), locale, platform `android`, session id and install id. `sdk` is `lyrelog-flutter/0.1.0 lyrelog-android/0.1.0`. |
| Secrets | Values under keys whose name is or ends with `authorization`, `cookie`, `password`, `token`, `secret`, `apikey` and the rest of the [shared list](/sdks#what-every-sdk-does-for-you) become `"[redacted]"`, at any depth, before anything is cut. | The same. |
| Limits | Long strings cut on a character boundary, extra attributes counted in `lyrelog_dropped_attrs`, payloads over 64 KiB summarized as `{"lyrelog_truncated": true, "bytes": N, "preview": "..."}`. | The same. |
Change the redaction list with `redactedKeys`: your list replaces the defaults, and an empty
list turns redaction off. To add to it:
```dart
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...',
redactedKeys: [...LyrelogConfiguration.defaultRedactedKeys, 'pin'],
));
```
## App Store privacy and Play data safety [#app-store-privacy-and-play-data-safety]
The Swift SDK's privacy manifest (`PrivacyInfo.xcprivacy`) ships inside the app, and Xcode merges
it into the app's privacy report, as on the
[Swift page](/sdks/swift#privacy-manifest-and-app-store-privacy).
For the App Store privacy label, declare what your app sends through Lyrelog:
- **Diagnostics:** Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
- **Identifiers > Device ID:** the install id, a random UUID that isn't the advertising id,
isn't backed up and is deleted on a denial (App Functionality). Not linked to the person
unless you also call `setUser`.
- **Identifiers > User ID**, linked to the person: only if you call `setUser`.
- **Usage Data > Product Interaction:** if you log screens (`screen_viewed`) or taps.
For the Play Console's data safety form:
- **App info and performance:** Crash logs, Diagnostics (App functionality, and Analytics if
you use it that way). Collected, not shared.
- **Device or other IDs:** the install id, as above.
- **App activity > App interactions:** if you log screens or taps.
On both, anything else your `attrs` or `payload` carry (emails, purchases...) goes under its own
category. Data is encrypted in transit (`https`). The server adds the country of the sending
address; the address itself isn't stored.
# Go
> Structured logs from your Go services, with a log/slog handler. Standard library only.
Source: https://docs.lyrelog.com/sdks/go
The module is `go.lyrelog.com/lyrelog`. It needs Go 1.24 or later and
has no dependencies.
Internal preview: this package isn't published yet. Until it is, `go get go.lyrelog.com/lyrelog`
fails: the repository is private and has no release yet.
## Install [#install]
```bash
go get go.lyrelog.com/lyrelog
```
## Start [#start]
```go
import "go.lyrelog.com/lyrelog"
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...", // a server key, or read it from your own config
Platform: "api",
})
if err != nil {
log.Fatal(err) // only for a bad config: logging itself never fails
}
defer client.Close() // sends what is left (waits at most 5 s)
```
Use a server key, `lyr_srv_...`, from the project's **API keys** page (**Send events from a
server**). It is a secret: keep it in your server's environment, never in an app or a web page.
Its events are [verified](/concepts/verification), and one address has no daily share of
the month. An ingest key, `lyr_ing_...`, works too, but its events aren't verified.
Only `APIKey` is required: without it `New` returns an error and a `nil` client. A `nil`
`*Client` does nothing, so code can log before (or without) one. `Endpoint` defaults to
`https://ingest.lyrelog.com`; it is the base URL, and a pasted `/v1/events:batch` path is
removed.
`log.Fatal` and `os.Exit` skip deferred calls, so `defer client.Close()` never runs after them.
In `main`, return an exit code from a function that does the work:
```go
func main() { os.Exit(run()) }
func run() int {
client, err := lyrelog.New(lyrelog.Config{APIKey: os.Getenv("LYRELOG_KEY")})
if err != nil {
fmt.Fprintln(os.Stderr, err) // client is nil and does nothing: carry on without it
}
defer client.Close() // runs before os.Exit
// ...
return 0
}
```
In a serverless function (AWS Lambda), call `client.Flush(ctx)` before the handler returns: the
runtime may freeze the process before the next send.
## Log events [#log-events]
One method per level: `Trace`, `Debug`, `Info`, `Notice`, `Warning`, `Error`, `Critical`, or
`Log(level, message, ...)`. Details are options: `lyrelog.Category`, `lyrelog.Attrs`,
`lyrelog.Payload` and `lyrelog.User`.
```go
client.Info("checkout_done", lyrelog.Attrs{"plan": "pro", "latency_ms": 412})
client.Error("payment_failed",
lyrelog.Category("billing"),
lyrelog.Attrs{"code": "card_declined"},
lyrelog.Payload(map[string]any{"response": body}),
)
```
Attributes can be strings, numbers, booleans, `nil`, string slices and nested maps (4 levels).
Names with dots are rewritten with `_`. Several `Attrs` options merge, a later key wins.
A `Payload` is encoded with `encoding/json`: pass `json.RawMessage` for bytes that already are
JSON (a plain `[]byte` arrives as a base64 string).
## Loggers for each area [#loggers-for-each-area]
```go
billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})
```
## Users [#users]
```go
client.SetUser("u_123") // attached to every following event
client.SetUser("") // clear it
```
A server handles many people at once: set the user on each event with
`lyrelog.User(id)`, which replaces the one from `SetUser` for that event.
## The slog handler [#the-slog-handler]
Send `log/slog` records to Lyrelog:
```go
logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")
```
- The record's message is the event's message, its time the event's time; attributes and groups
become nested attributes.
- A top-level `category` string attribute sets the area (and isn't sent as an attribute);
without one the handler's `Category` is used.
- Levels: `Debug-4` and below is `trace`, `Debug` is `debug`, `Info` is `info`, between `Info` and
`Warn` is `notice`, `Warn` is `warning`, `Error` is `error`, `Error+4` and above is `critical`.
- `SlogOptions.Level` adds a minimum on top of the client's; `AddSource` adds a `source`
attribute with the caller's function, file and line. Build with `go build -trimpath` so the
file holds module paths rather than your build machine's directories.
To keep printing to the terminal as well, send each record to both handlers. On Go 1.26 or later,
`slog.NewMultiHandler` does it:
```go
logger := slog.New(slog.NewMultiHandler(
slog.NewTextHandler(os.Stderr, nil),
lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)
```
## A net/http middleware [#a-nethttp-middleware]
There is no built-in middleware. This one records every request as `http_request_served` in the
`http` area, at info, warning for a 4xx and error for a 5xx, with the route pattern rather than
the path, so ids don't explode the cardinality:
```go
func logRequests(client *lyrelog.Client, next http.Handler) http.Handler {
httpLog := client.Logger("http")
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
next.ServeHTTP(recorder, r)
level := lyrelog.LevelInfo
switch {
case recorder.status >= 500:
level = lyrelog.LevelError
case recorder.status >= 400:
level = lyrelog.LevelWarning
}
httpLog.Log(level, "http_request_served", lyrelog.Attrs{
"method": r.Method,
"route": r.Pattern, // set by http.ServeMux (Go 1.23+), e.g. "GET /users/{id}"
"status": recorder.status,
"duration_ms": time.Since(start).Milliseconds(),
})
})
}
type statusRecorder struct {
http.ResponseWriter
status int
}
func (s *statusRecorder) WriteHeader(code int) {
s.status = code
s.ResponseWriter.WriteHeader(code)
}
// Unwrap lets http.ResponseController reach the original writer (Flush, deadlines).
func (s *statusRecorder) Unwrap() http.ResponseWriter { return s.ResponseWriter }
// http.ListenAndServe(":8080", logRequests(client, mux))
```
`r.Pattern` is empty for a request no route matched.
## Errors [#errors]
```go
if err := charge(ctx, order); err != nil {
client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}
```
The event is `exception`, level `error`, with `error_type` and `error_message` in the
attributes and, in the payload, the error's chain (each wrapped error) and the stack. A
`nil` error logs nothing. `Logger.CaptureError` does the same with the logger's category. The
level is always `error`: for another one, log the error yourself with `Log`.
## Panics [#panics]
The SDK doesn't recover panics. `net/http` recovers a handler's panic and only prints it, so
record it in a middleware, outside the one above:
```go
func recoverPanics(client *lyrelog.Client, next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
v := recover()
if v == nil {
return
}
if v == http.ErrAbortHandler {
panic(v)
}
err, ok := v.(error)
if !ok {
err = fmt.Errorf("panic: %v", v)
}
client.CaptureError(err, lyrelog.Category("http"),
lyrelog.Attrs{"handled": false, "mechanism": "panic", "route": r.Pattern})
http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
}()
next.ServeHTTP(w, r)
})
}
// http.ListenAndServe(":8080", recoverPanics(client, logRequests(client, mux)))
```
The stack in the payload is taken where the panic was recovered, so it still shows the frames
that panicked. A panic in a goroutine of your own crashes the program before anything is sent:
recover it in that goroutine the same way.
## Environments and platform [#environments-and-platform]
`Environment` defaults to the `LYRELOG_ENVIRONMENT` environment variable (lowercased), else
`production`. `Platform` defaults to `go`. Set either in the config:
```go
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...",
Environment: "staging",
Platform: "worker",
})
```
Both must be lowercase letters, digits, `-` and `_`, up to 32, starting with a letter or digit.
An invalid `Config.Environment` or `Config.Platform` makes `New` return an error; an invalid
`$LYRELOG_ENVIRONMENT` is reported to `ErrorLog` and replaced by `production`, so a typo in a
deploy never stops a service.
`Release` defaults to the main module's version from the build info, and `AppID` to the main
module's path.
## Consent [#consent]
Consent is for apps that run on someone's device. A server SDK sends what it is given.
## Flush and stop [#flush-and-stop]
```go
err := client.Flush(ctx) // send what's queued now
client.Close() // flush (up to CloseTimeout) and stop
```
`Flush` sends everything queued before the call and waits for it or for `ctx`. It returns:
- `nil` when everything reached the server;
- `ctx.Err()` if the context ended first;
- `ErrUnauthorized` after a `401` or `403` (the client stops sending until the process restarts
and keeps its queue);
- an error saying a batch was refused and dropped (the rest was still sent);
- an error saying delivery failed and will be retried, with the events kept. Inside a
`Retry-After` the server asked for, `Flush` returns this at once and sends nothing;
- `ErrClosed` after `Close`.
`Close` waits at most `CloseTimeout` for the last flush and returns the same values; events still
unsent then are dropped and counted in `Stats().Dropped`. After `Close`, log calls do nothing.
`client.Stats()` returns `Queued` (waiting, including a batch being retried), `Sent` (accepted by
the server), `Rejected` (lines the server refused, never resent) and `Dropped` (by the client:
queue overflow, a refused batch, or left at `Close`).
## In development and tests [#in-development-and-tests]
Without an `APIKey`, `New` returns an error and a `nil` client, and a `nil` client does nothing:
the same code runs in tests and on a laptop without a key, as in the `run` example above. The
slog handler over a `nil` client drops every record.
To see what a test logs, pass an `HTTPClient` whose `Transport` records the requests, or point
`Endpoint` at an `httptest.Server` (plain `http://` is allowed for loopback addresses).
## Verified events [#verified-events]
A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).
Send with a server key, `lyr_srv_...`. Every event it sends is verified (`verified_by` is
`server`) and doesn't count toward the
[daily share of one address](/concepts/verification#the-daily-share-of-one-address). An owner
makes it on the project's **API keys** page, **Send events from a server**, after a recent sign-in
(within 10 minutes), and it is shown once. It is a secret: keep it out of the repository and read
it from the server's environment or secret store.
```go
client, err := lyrelog.New(lyrelog.Config{
APIKey: os.Getenv("LYRELOG_KEY"), // lyr_srv_..., set in the server's environment
})
```
To check, open the [explorer](/dashboard/explorer): in **Filter**, pick **Verified by** and
**Server key** (the other values are **App Attest** and **Not verified**). An opened event says it under
**Context**, in its **Sender** line: **Verified, server key**, or **Not verified, public key**.
Events sent with an ingest key, `lyr_ing_...`, or a full-access key, `lyr_adm_...`, arrive
unverified: anyone holding a public key could have sent the same, and they count toward the daily
share. A verified event proves who sent it, not that what it says is true.
See [Verified events](/concepts/verification) for who verifies what and the daily share.
## Configuration [#configuration]
| Field | Default | Meaning |
|---|---|---|
| `Endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is removed. Plain `http://` only for localhost |
| `APIKey` | required | The project's server key (`lyr_srv_...`), or an ingest key |
| `Environment` | `$LYRELOG_ENVIRONMENT`, else `production` | Any valid name |
| `Platform` | `go` | `api`, `worker`... |
| `Release` | the module version | Sent as `resource.app_version` |
| `AppID` | the module path | Sent as `resource.app_id` |
| `MinimumLevel` | `LevelDebug` | Events below it are dropped before queueing |
| `FlushInterval` | 5 s | How often the background goroutine sends |
| `MaxQueue` | 10,000 | Oldest dropped beyond it, counted in `Stats().Dropped` |
| `MaxQueueBytes` | 16 MiB | The same cap, in bytes |
| `CloseTimeout` | 5 s | How long `Close` waits for the last flush |
| `HTTPClient` | 30 s timeout | The client that sends batches. Redirects are never followed, even with your own client |
| `ErrorLog` | stderr, once | Receives the SDK's own diagnostics, each starting with `lyrelog: `. Without it, only the first refused key or dropped batch (once) and the quota warning are printed to stderr. Don't point it at a logger that feeds this client |
## Delivery and limits [#delivery-and-limits]
- One background goroutine batches up to 500 events or 512 KiB, gzipped; a full batch is sent
right away. Safe for concurrent use.
- Retries with full jitter (1 s doubling to 5 min), honoring `Retry-After` (seconds or a date),
resending the same bytes. Any other 4xx drops the batch; a 3xx drops it and logs a warning.
- Values under keys whose name is or ends with `authorization`, `cookie`, `password`, `token`,
`secret`, `apikey` and the rest of the [shared list](/sdks#what-every-sdk-does-for-you)
become `"[redacted]"` before queueing: in attributes and the payload, at any depth (maps,
structs by their JSON names, slices, `http.Header`), before anything is cut. `Config.RedactKeys`
replaces the list and an empty, non-nil slice turns it off; to add to it,
`RedactKeys: append(lyrelog.DefaultRedactKeys(), "pin")`.
- When a Free organization has used its month's events, the server answers `429`. The events
stay in memory and go out once the server takes them again, up to `MaxQueue`. The client
logs one warning to `ErrorLog` (or stderr) and says nothing more until a batch is accepted.
- Context: `os_name` is `runtime.GOOS`, `app_build` the VCS revision when the binary has one, and
the install and session ids are per process.
- Limits are applied before queueing: past 200 leaves attributes are dropped and counted in
`lyrelog_dropped_attrs`, dots in names become `_` (`http.status` is `http_status`), errors,
times, durations and `Stringer`s become strings, structs their JSON form, NaN `null`. A payload
over 64 KiB becomes `{"lyrelog_truncated": true, "bytes": N, "preview": "..."}` with its first
KiB. One event's attributes are capped at 256 KiB encoded, and an event that can't fit in a
512 KiB batch is dropped and counted.
- Printing a `Config` or a `*Client` with `fmt` hides the API key.
# SDKs
> The same model in every language. Pick yours, or send events over HTTP.
Source: https://docs.lyrelog.com/sdks
The Lyrelog SDKs share one model (levels, areas, attributes, users) and use the same names where
the language allows, in its own casing. The table shows where they differ.
### Apps [#apps]
| | Swift | Android | React Native | Flutter |
|---|---|---|---|---|
| Start | `Lyrelog.start(Configuration(...))` | `Lyrelog.start(context, Configuration(...))` | `Lyrelog.init({...})` | `Lyrelog.start(LyrelogConfiguration(...))` |
| Log | `Lyrelog.info("checkout_done", attrs:)` | `Lyrelog.info("checkout_done", attrs = ...)` | `Lyrelog.info("checkout_done", { attrs })` | `Lyrelog.info('checkout_done', attrs: {...})` |
| Area logger | `Lyrelog.Logger(category: "checkout")` | `Lyrelog.logger("checkout")` | `Lyrelog.logger("checkout")` | `Lyrelog.logger('checkout')` |
| User | `Lyrelog.setUser("u_123")` | `Lyrelog.setUser("u_123")` | `Lyrelog.setUser("u_123")` | `Lyrelog.setUser('u_123')` |
| Screen | `Lyrelog.screen("Settings")` | `Lyrelog.screen("Settings")` | `trackNavigation(ref)`, or `Lyrelog.screen("Settings")` | `LyrelogNavigatorObserver()`, or `Lyrelog.screen('Settings')` |
| Requests | `session.loggedData(for:)` | | | |
| Capture an error | `Lyrelog.captureError(error)` | `Lyrelog.captureError(e)` | `Lyrelog.captureException(error)` | `Lyrelog.captureError(e, stackTrace: s)` |
| Uncaught errors and crashes | MetricKit crashes and hangs, automatic | Uncaught exceptions, automatic, sent on the next launch | Fatal JavaScript and render errors as crashes, rejections and other errors, plus the native crashes; automatic | Dart errors (`FlutterError`, `PlatformDispatcher`), plus the native crashes; automatic |
| Flush | `await Lyrelog.flush()` | `Lyrelog.flush()` (off the main thread) | `await Lyrelog.flush()` | `await Lyrelog.flush()` |
| Stop | `await Lyrelog.stop()` | `Lyrelog.stop()` | `await Lyrelog.close()` | `await Lyrelog.stop()` |
### Web and servers [#web-and-servers]
| | JavaScript | Python | Go | JVM |
|---|---|---|---|---|
| Start | `Lyrelog.init({...})` | `lyrelog.init(...)` | `lyrelog.New(lyrelog.Config{...})` | `Lyrelog.start(Configuration(...))` |
| Log | `client.info("checkout_done", { attrs })` | `lyrelog.info("checkout_done", attrs=)` | `client.Info("checkout_done", lyrelog.Attrs{})` | `Lyrelog.info("checkout_done", attrs = ...)` |
| Area logger | `client.logger("checkout")` | `lyrelog.logger("checkout")` | `client.Logger("checkout")` | `Lyrelog.logger("checkout")` |
| User | `client.setUser("u_123")` | `lyrelog.set_user("u_123")` | `client.SetUser("u_123")` | `Lyrelog.setUser("u_123")`, or `Lyrelog.userScope(id)` for a thread |
| Screen | `client.screen("Settings")` | | | |
| Capture an error | `client.captureException(err)` | `lyrelog.capture_exception(exc)` | `client.CaptureError(err)` | `Lyrelog.captureError(e)` |
| Uncaught errors and crashes | `window` and Node, automatic | your own `sys.excepthook` | your own `recover` | `captureUncaught = true` (off by default) |
| Flush | `await client.flush()` | `lyrelog.flush()` | `client.Flush(ctx)` | `Lyrelog.flush()` |
| Stop | `await client.close()` | `lyrelog.shutdown()` | `client.Close()` | `Lyrelog.close()` (a shutdown hook does it on exit) |
| Standard logging | | `lyrelog.LoggingHandler()` | `lyrelog.NewSlogHandler(client, nil)` | `LyrelogAppender` for Logback |
The app SDKs can also copy every event to the platform's own log, so it shows in Xcode and
logcat: `mirrorToOSLog` in Swift, `mirrorToLogcat` on Android, `mirrorToNativeLog` in React
Native and `mirrorToConsole` in Flutter.
None of the SDKs is published yet, so every install command on these pages fails for now:
`pnpm add`, `flutter pub add` and `uv add` find no package, Gradle and Maven find nothing on
Maven Central, and Swift Package Manager and `go get` can't reach the private repositories. Each page shows the line as it will be once the SDKs are published.
## What every SDK does for you [#what-every-sdk-does-for-you]
The React Native and Flutter SDKs send through the Swift SDK on iOS and the Android SDK on
Android, so everything below is theirs, done the native way. The JVM SDK runs the Android SDK's
engine, set up for a server.
- **Never blocks or throws** in your code. Logging copies the event into a queue and returns; a
background worker sends it.
- **Batches** up to 500 events or about 512 KiB per request, one NDJSON line per event, gzipped
where the platform can.
- **Sends to `https://ingest.lyrelog.com`** unless you set another `endpoint`. The endpoint is
the base URL: if you paste the whole `.../v1/events:batch` address, the SDK strips the path.
A wrong endpoint (a `404`, or a redirect) is reported as a warning in the SDK's own log.
- **Retries** temporary failures (`408`, `425`, `429`, 5xx, network errors) with exponential backoff
(1 s doubling up to 5 min) and jitter, honoring `Retry-After`, also when you call `flush` or
close the client. Every SDK but Python uses full jitter (a random wait between 0 and the
ceiling); Python uses equal jitter (between half the ceiling and the ceiling).
- **Drops a refused batch.** Any other 4xx (`400`, `413`, `415`...) means the batch itself is
wrong, so it is dropped rather than resent. A refused key (`401`, `403`) stops sending until the
app or process restarts, and keeps the events. Redirects are never followed: a 3xx answer drops
the batch and logs a warning, since it means the endpoint is wrong.
- **Keeps events through a `429`.** When a Free organization has used its month's events, or a
project goes over its rate limit, the SDK keeps the batch and tries again after `Retry-After`
(see [HTTP API](/http-api#responses)). The app SDKs (Swift, Android, React Native,
Flutter) keep them on disk across launches. The JVM SDK keeps them on disk too, in a temporary
directory for the process unless you give it a `storageDirectory`. JavaScript, Python and Go
keep them in memory. Either way the caps below still apply.
- **Caps** what waits: 10,000 events and 16 MiB in memory by default in JavaScript, Python and
Go; 20 MB on disk and 7 days in the app SDKs and the JVM. The oldest go first.
- **Redacts secrets**, the same way in every SDK. A field's value becomes `"[redacted]"` when
its name, lowercased and without `-`, `_`, `.` or spaces, is or ends with `authorization`,
`cookie`, `password`, `passwd`, `secret`, `token`, `apikey`, `privatekey`, `credential(s)`,
`accesskey` or `signature`. So `X-Api-Key`, `csrf_token` and `Set-Cookie` are redacted, and
`token_count` and `max_tokens` aren't. It happens at any depth of attributes and payload,
before anything is cut, so a secret never survives in a shortened string or a payload's
preview. Only names are checked: a secret inside a message or an error's text is sent as is.
Change the list with `redactedKeys` (Swift, Android, Flutter, JVM), `redactKeys` (JavaScript,
React Native), `redact_keys` (Python) or `RedactKeys` (Go): your list replaces it, and an empty
one turns redaction off. To add to it, extend the exported defaults:
`Configuration.defaultRedactedKeys` in Swift, `Configuration.DEFAULT_REDACTED_KEYS` on Android
and the JVM, `LyrelogConfiguration.defaultRedactedKeys` in Flutter, `DEFAULT_REDACT_KEYS` in
JavaScript, React Native and Python, `DefaultRedactKeys()` in Go. The JavaScript and Python SDKs also take a
`beforeSend` / `before_send` hook to change or drop any event.
- **Flushes** on a timer (15 s in the app SDKs, 5 s on the web and servers), when you call
`flush`, when an app goes to the background, and on shutdown.
- **Fits events to the server's limits** before queueing them, so it never sends a line the
server would reject for its shape.
## Configuration [#configuration]
The same settings exist in every SDK, under each language's names. Each SDK page has the full
list.
### Apps [#apps-1]
| Setting | Swift | Android | React Native | Flutter | Default |
|---|---|---|---|---|---|
| Key | `apiKey` | `apiKey` | `apiKey` | `apiKey` | required: an ingest key |
| Endpoint | `endpoint` | `endpoint` | `endpoint` | `endpoint` | `https://ingest.lyrelog.com` |
| Environment | `environment` | `environment` | `environment` | `environment` | detected, see [Environments](/concepts/environments) |
| Platform | `platform` | `platform` | `platform` | `platform` | the OS, see [Platforms](/concepts/platforms) |
| Version | from the bundle | `appVersion`, else from the package | from the app | from the app | sent as `resource.app_version` |
| App id | from the bundle | the package name | the bundle id or package name | the bundle id or package name | sent as `resource.app_id` |
| Lowest level kept | `minimumLevel` | `minimumLevel` | `minimumLevel` | `minimumLevel` | `debug` |
| Send interval | `uploadInterval` | `flushIntervalMillis` | `flushIntervalMs` | `flushInterval` | 15 s |
| Queue size | `maxDiskBytes` | `maxDiskBytes` | `maxDiskBytes` | `maxDiskBytes` | 20 MB on disk |
| Consent | `consent` | `consent` | `consent` | `consent` | `granted` |
| Prove the app ([verified events](/concepts/verification)) | `appAttest` | `attest` | `attest` | `attest` | on |
### Web and servers [#web-and-servers-1]
| Setting | JavaScript | Python | Go | JVM | Default |
|---|---|---|---|---|---|
| Key | `apiKey` | `api_key` | `APIKey` | `apiKey` | required: an ingest key in browsers, a [server key](/concepts/verification#servers) on servers |
| Endpoint | `endpoint` | `endpoint` | `Endpoint` | `endpoint` | `https://ingest.lyrelog.com` |
| Environment | `environment` | `environment` | `Environment` | `environment` | detected, see [Environments](/concepts/environments) |
| Platform | `platform` | `platform` | `Platform` | `platform` | detected, see [Platforms](/concepts/platforms) |
| Version | `release` | `release` | `Release` | `release`, else the jar's manifest | sent as `resource.app_version` |
| App id | `appId` | `app_id` | `AppID` | `appId`, else the jar's manifest | sent as `resource.app_id` |
| Lowest level kept | `minimumLevel` | `minimum_level` | `MinimumLevel` | `minimumLevel` | `debug` |
| Send interval | `flushIntervalMs` | `flush_interval` | `FlushInterval` | `flushIntervalMillis` | 5 s |
| Queue size | `maxQueue` | `max_queue` | `MaxQueue` | `maxDiskBytes` | 10,000 events in memory; 20 MB on disk on the JVM |
| Consent | `consent` | | | | `granted` (browsers) |
In the JavaScript and Go columns the instance is called `client` (`log` in the JavaScript
examples); the other SDKs log through `Lyrelog` or the `lyrelog` module. The counters are named
after each language too: JavaScript and Python count `delivered`, Go `Sent`.
## When events don't show up [#when-events-dont-show-up]
1. **Check the environment.** The dashboard opens on `production`. Swift sends `development`
from Xcode and the simulator, Android from every debug build, and React Native and Flutter
apps do as the native SDK under them does. JavaScript sends `development` on `localhost`, and
on Node whenever `NODE_ENV` isn't `production`, including when it's unset. Pick the environment, or
**All environments**, in the top bar.
2. **Read the SDK's own messages.** Swift: the unified log, subsystem `com.lyrelog.sdk`, at
debug level (in Console, turn on **Include Debug Messages**). Android: logcat, tag `Lyrelog`,
at debug level. React Native and Flutter: the native SDK's, in the same places; React Native
also warns once in Metro, in development builds, when the key or the native module is missing.
JavaScript: console lines starting with `[lyrelog]`. Python: the `lyrelog` logger. Go:
`Config.ErrorLog`; without it, the first problem is printed to stderr once. JVM: standard
error, lines starting with `lyrelog: `, or `Configuration.diagnostics`. They say when the key was refused, the endpoint
is wrong or a batch was dropped.
3. **Let the process send before it ends.** Short scripts, serverless functions and processes
that call `exit` must flush or close the client first. The JVM SDK's shutdown hook does it on
a normal exit, but a serverless handler still has to flush. See each SDK's page.
4. **Check consent and level.** With consent `pending` nothing is sent. Events below the lowest
level kept are never queued.
5. **Check the key.** After a `401` or `403`, nothing more is sent until the app or process
restarts. An empty key sends nothing (in Go, `New` returns an error; on the JVM, `start`
returns `false`).
## What not to send [#what-not-to-send]
Use `message` for a stable event name, never for text with personal data in it. Use your own ids
for people (`setUser`, `user_id`), not email addresses. Keep tokens, passwords and full request or
response bodies with their headers out of attributes and payloads. Redaction is a safety net for
the key names it knows, not a filter you can rely on.
## In development and tests [#in-development-and-tests]
- **Swift:** don't call `Lyrelog.start` in tests. Anything logged before `start` is ignored.
- **Android:** the same, don't call `Lyrelog.start` in unit tests. Debug builds send
`development`; reaching an endpoint on your computer from the emulator needs a few settings,
see [In development and tests](/sdks/android#in-development-and-tests).
- **React Native:** don't call `Lyrelog.init` in tests: calls before `init` are ignored. Debug
builds send `development`.
- **Flutter:** don't call `Lyrelog.start` in widget and unit tests: anything logged before
`start` is ignored. On platforms the plugin doesn't support (web, desktop) every call does
nothing. See [In development and tests](/sdks/flutter#in-development-and-tests).
- **JavaScript:** leave `apiKey` empty and the client warns once and sends nothing, or pass
`consent: "denied"`.
- **Python:** an empty `api_key` gives a client that accepts events and sends nothing.
- **Go:** `New` returns an error without an `APIKey`, and a `nil` `*Client` does nothing, so the
same code runs without one.
- **JVM:** leave the key out: `start` returns `false` and every call does nothing, the Logback
appender included.
# JavaScript
> Structured logs from a website or a Node service. TypeScript, ESM, no dependencies.
Source: https://docs.lyrelog.com/sdks/javascript
One package, `@lyrelog/js`, for browsers and Node 22.12 or later. The same import works
everywhere: bundlers pick the browser build, Node picks the Node build. The package is ESM only:
`import` it, or `require()` it (Node 22.12 loads ES modules without a flag).
Internal preview: this package isn't published yet. Until it is, `pnpm add @lyrelog/js` fails:
there is no package on npm.
## Install [#install]
```bash
pnpm add @lyrelog/js
```
## Start [#start]
`Lyrelog.init` returns a client. Make one per page load or per process, as early as possible.
```ts
import { Lyrelog } from "@lyrelog/js";
export const log = Lyrelog.init({
apiKey: "lyr_ing_...", // ingest-only: it can append events, never read them
release: "2.0.1",
});
```
```ts
import { Lyrelog } from "@lyrelog/js";
export const log = Lyrelog.init({
apiKey: process.env.LYRELOG_KEY!, // a server key, lyr_srv_..., kept on the server
platform: "api", // "node" unless you say
});
```
In the browser, use the project's ingest key, `lyr_ing_...`: it can only append events, so it is
safe in a page. On Node, use a server key, `lyr_srv_...`: its events are
[verified](/concepts/verification) and one address has no daily share of the month. Never
put a server key in browser code. To get verified events from a page, send them
[through your own server](/concepts/verification#web-pages-through-your-own-server).
Events go to `https://ingest.lyrelog.com`. Pass `endpoint` only to send them somewhere else. It's
the base URL; a pasted `.../v1/events:batch` path is stripped.
Calling `init` again with the same endpoint and key gives back the live client when the config is
the same, and otherwise closes it and starts a new one, so a hot reload never leaves two clients.
Without an `apiKey`, or with an endpoint that isn't https (plain http only on `localhost`), the
client warns once in the console and sends nothing.
### Content Security Policy [#content-security-policy]
If your site sets a Content Security Policy, allow the ingest in `connect-src`:
```text
Content-Security-Policy: connect-src 'self' https://ingest.lyrelog.com
```
## Log events [#log-events]
One method per level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`, or
`log(level, message, options)`.
```ts
log.info("checkout_done", { category: "checkout", attrs: { items: 3, total_cents: 4200 } });
log.error("job_failed", { attrs: { job: "digest" }, payload: { response: raw } });
```
A log call fits the event to the server's limits, serializes it (later changes to your objects
don't leak in) and queues it. Bad input is turned into something valid, never an exception.
After `close()`, log calls do nothing.
## Loggers for each area [#loggers-for-each-area]
```ts
const jobs = log.logger("jobs");
jobs.info("job_done", { attrs: { job: "digest", ms: 412 } });
```
A logger has every level method and `log`. To capture an error in its area, use
`log.captureException(error, { category: "jobs" })`.
## Users [#users]
```ts
log.setUser(accountId); // attached to every following event
log.setUser(null); // on sign-out
```
`log.sessionId` gives the current session, for example for a support screen. The user id isn't
saved: in the browser, call `setUser` again on each page load once you know who the person is.
## Screens [#screens]
```ts
log.screen("Checkout");
```
Logs `screen_viewed` in the `navigation` area with the screen before and the seconds spent on it,
and every following event carries `screen`. On the web, call it when the page changes. Name the
screen rather than passing the URL: `/orders/1234` would make one screen per order.
```tsx
function OrderPage() {
useEffect(() => log.screen("Order"), []);
// ...
}
```
## Requests [#requests]
There is no automatic request logging. Log the requests you care about with a stable name and the
fields you want to chart, as the [Swift SDK](/sdks/swift#network-requests) does:
```ts
const started = performance.now();
const res = await fetch("/api/cart");
log.log(res.ok ? "debug" : "warning", res.ok ? "http_request" : "http_request_failed", {
category: "network",
attrs: { method: "GET", path: "/api/cart", status: res.status, duration_ms: Math.round(performance.now() - started) },
});
```
## Exceptions [#exceptions]
```ts
try {
await pay();
} catch (error) {
log.captureException(error, { category: "checkout", attrs: { step: "pay" } });
}
```
Records `exception` (level `error`, or `level` if you pass one) with `error_type` and
`error_message` as attributes, and the name, message, stack, `code` and up to three `cause`s in
the payload. Anything thrown works, not only `Error`. From a thrown value that isn't an `Error`,
only its `name`, `message`, `code` and `status` are kept, never the rest of the object (an HTTP
client's error would carry its request headers). In the browser, URLs in stacks lose their query
string and fragment.
### Uncaught errors [#uncaught-errors]
They are captured for you, as the same `exception` event with `handled: false` and a
`mechanism`:
- **In the browser**, errors that reach `window` (`onerror`) and promises rejected with no
handler (`onunhandledrejection`). The console still shows them. The opaque cross-origin
"Script error." carries nothing useful and is skipped.
- **On Node**, an uncaught exception or rejection. Lyrelog only watches (it uses
`uncaughtExceptionMonitor`), so the process still crashes as it would without it. There's no
time to send before it exits, so the event is written to a small file in the temp folder and
sent the next time the app starts with the same key.
At most 10 a minute are captured, and the same error once every 10 seconds, so a loop that
throws can't flood your project; `stats().skippedErrors` counts what was skipped. Turn it all off
with `captureErrors: false`.
### Errors your framework catches [#errors-your-framework-catches]
Errors a framework catches itself never become uncaught: call `captureException` there. In
React, from an error boundary:
```tsx
import { Component, type ErrorInfo, type ReactNode } from "react";
class ErrorBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
state = { failed: false };
static getDerivedStateFromError() {
return { failed: true };
}
componentDidCatch(error: unknown, info: ErrorInfo) {
log.captureException(error, { category: "ui", attrs: { component_stack: info.componentStack ?? "" } });
}
render() {
return this.state.failed ? Something went wrong.
: this.props.children;
}
}
```
In Express, from an error handler, added after your routes:
```ts
app.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
log.captureException(err, {
category: "http",
attrs: { method: req.method, route: req.route?.path ?? "unmatched" },
});
next(err);
});
```
## Environments and platform [#environments-and-platform]
- **Node:** `environment` is `production` only when `NODE_ENV=production`. Anything else,
including no `NODE_ENV` at all, is `development`: set `NODE_ENV=production` (or `environment`)
on your servers. `platform` is `node`.
- **Browser:** `environment` is `development` on `localhost`, `127.0.0.1`, `[::1]` or a
`.localhost` host, else `production`. `platform` is `web`.
Set either in `init`, for example `Lyrelog.init({ apiKey, environment: "staging" })`.
Any name works: lowercase letters, digits, `-` and `_`, up to 32.
## Consent [#consent]
```ts
const log = Lyrelog.init({ apiKey, consent: "pending" });
// later
log.setConsent("granted"); // or "denied"
```
`pending` keeps events in memory unsent, `granted` sends them, `denied` drops everything (and, on
Node, the file of uncaught errors waiting to be sent).
Consent isn't saved between page loads: store the person's choice yourself and pass it to `init`.
In the browser, until consent is granted the install and session ids stay in memory, not in
`localStorage` or `sessionStorage`.
## Redacting and filtering [#redacting-and-filtering]
A value becomes `"[redacted]"`, in attributes, the payload and anything turned into a string, when
its key name, lowercased and without `-`, `_`, `.` or spaces, is or ends with one of
`authorization`, `cookie`, `password`, `passwd`, `secret`, `token`, `apikey`, `privatekey`,
`credential`, `credentials`, `accesskey` or `signature`. So `X-Api-Key`, `csrf_token`,
`Set-Cookie` and `user_token` are redacted; `token_count` and `max_tokens` aren't. `redactKeys`
replaces this list with your own names, matched the same way; an empty list turns redaction off.
To add to the defaults, spread `DEFAULT_REDACT_KEYS`, which the package exports.
To change or drop events yourself, pass `beforeSend`. It gets each event after redaction and
before it's queued, and returns it, changed or not, or `null` to drop it. The ids, `ts` and
`resource` can't be changed, what you return is fitted to the limits again, and a hook that throws
drops the event.
```ts
import { Lyrelog, DEFAULT_REDACT_KEYS } from "@lyrelog/js";
const log = Lyrelog.init({
apiKey: "lyr_ing_...",
redactKeys: [...DEFAULT_REDACT_KEYS, "card_number"],
beforeSend(event) {
if (event.message === "health_check") return null;
if (event.attrs?.email) event.attrs.email = "[redacted]";
return event;
},
});
```
## Flush and stop [#flush-and-stop]
In the browser you rarely need either: the timer and hiding the page already send.
```ts
await log.flush(); // send what is queued now
```
On Node, close the client in your shutdown path, so what is queued goes out before the process
exits:
```ts
process.on("SIGTERM", async () => {
await log.close(); // sends what is queued, then stops
process.exit(0);
});
```
A script that ends with `process.exit()` skips `beforeExit` and loses what is still queued:
`await log.close()` first, as above.
In a serverless function (AWS Lambda, Vercel and Netlify functions, Cloudflare Workers), the
runtime freezes or ends the function as soon as it answers, before the timer fires. Flush before
returning:
```ts
export async function handler(event) {
log.info("order_created", { attrs: { order_id: event.id } });
await log.flush();
return { statusCode: 200 };
}
```
`flush`, `close` and the send on page hide all respect a `Retry-After` the server asked for:
inside one, `flush` returns at once and the events wait.
`log.stats()` returns `{ queued, queuedBytes, dropped, delivered, rejected, skippedErrors, disabled }`;
`disabled` is true after a `401` or `403`, or when the client has no key or endpoint to send to.
## In development and tests [#in-development-and-tests]
Leave `apiKey` empty and the client warns once and sends nothing, or pass `consent: "denied"` to
drop every event without a warning:
```ts
const log = Lyrelog.init({
apiKey: process.env.LYRELOG_KEY ?? "",
consent: process.env.NODE_ENV === "test" ? "denied" : "granted",
});
```
## Verified events [#verified-events]
A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).
On Node, send with a server key, `lyr_srv_...`. Every event it sends is verified (`verified_by`
is `server`) and doesn't count toward the
[daily share of one address](/concepts/verification#the-daily-share-of-one-address). An owner
makes it on the project's **API keys** page, **Send events from a server**, after a recent sign-in
(within 10 minutes), and it is shown once. It is a secret: keep it out of the repository and read
it from the server's environment or secret store.
```ts
export const log = Lyrelog.init({
apiKey: process.env.LYRELOG_KEY!, // lyr_srv_..., set in the server's environment
});
```
In a browser the key is the public ingest key, so a page's events arrive unverified, and they
count toward the daily share. **Never put a server key in browser code**: anything in the page can
be read. To verify a site's events, relay them
[through your own server](/concepts/verification#web-pages-through-your-own-server): point
`endpoint` at a route on your backend that forwards each batch with the server key. That route
must accept events only from your own signed-in sessions, or it verifies nothing.
To check, open the [explorer](/dashboard/explorer): in **Filter**, pick **Verified by** and
**Server key** (the other values are **App Attest** and **Not verified**). An opened event says it under
**Context**, in its **Sender** line: **Verified, server key**, or **Not verified, public key**.
Events sent with an ingest key or a full-access key, `lyr_adm_...`, arrive unverified: anyone
holding a public key could have sent the same. A verified event proves who sent it, not that
what it says is true.
See [Verified events](/concepts/verification) for who verifies what and the daily share.
## Configuration [#configuration]
| Option | Default | Meaning |
|---|---|---|
| `endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is stripped. https only, http only on localhost |
| `apiKey` | required | Browser: the project's ingest key, safe in client code. Node: a server key, never in client code. Without it the client sends nothing |
| `environment` | detected | Any name: lowercase letters, digits, `-` and `_`, up to 32 |
| `platform` | `web` / `node` | `api`, `worker`... |
| `release` | Node: `npm_package_version` | Sent as `app_version`. The default exists only when started through a package script: pass it yourself under `node server.js`, Docker or systemd |
| `appId` | Web: the host name. Node: `npm_package_name` | Sent as `app_id`. On Node, the same caveat as `release` |
| `minimumLevel` | `debug` | Events below it are dropped before queueing |
| `flushIntervalMs` | `5000` | How often the queue is sent |
| `maxQueue` | `10000` | Events waiting in memory; beyond it the oldest go |
| `maxQueueBytes` | 16 MiB | The same cap, in bytes |
| `redactKeys` | `DEFAULT_REDACT_KEYS` | Key names to redact; replaces the defaults, `[]` turns it off |
| `beforeSend` | none | Change an event, or return `null` to drop it |
| `consent` | `granted` | `granted`, `pending` or `denied` |
| `captureErrors` | `true` | Capture uncaught errors and unhandled rejections |
## Delivery and limits [#delivery-and-limits]
| | |
|---|---|
| When it sends | Every 5 s, as soon as 500 events wait, on `flush()` and `close()`. In the browser also when the page hides; on Node on `beforeExit` (not on `process.exit()`; the timer never keeps the process alive). |
| Batches | Up to 500 events or 512 KiB, NDJSON, gzip (`CompressionStream` in browsers, `zlib` on Node). An event over 1 MiB is dropped and counted. |
| Retries | Backoff with full jitter (1 s doubling to 5 min), honoring `Retry-After`. A retry resends the same events with the same ids. Any other 4xx drops the batch; a 3xx drops it with a warning (redirects aren't followed); a refused key stops sending until restart and keeps the events. |
| Monthly quota | When a Free organization has used its month's events, the server answers `429`. The events stay in the queue and go out once the server takes them again, up to `maxQueue`. The client logs one `console.warn` with the server's message, and again only after a batch has been accepted in between. |
| Its own problems | A wrong endpoint, a redirect or a dropped batch: one `console.warn` starting with `[lyrelog]`. A refused key and rejected lines: `console.debug`, so turn on verbose messages in the browser's console to see them. |
| Context | Web: `os_name: "web"`, the browser family as `device_model`, `navigator.language` as `locale`, an install id in `localStorage` and a session id in `sessionStorage` (new after 30 min idle). Node: `process.platform`, `os.release()`, the CPU architecture, and ids per process. Storage that throws (private mode) falls back to memory. |
| Limits | Fitted before queueing; extra attributes are counted in `lyrelog_dropped_attrs`, dots in attribute names become `_`, a payload over 64 KiB becomes a summary with a preview. |
Worth knowing:
- **The queue lives in memory.** Events still waiting when a tab closes for good, or a process
is killed with `SIGKILL` or ends with `process.exit()`, are lost. Call `close()` in your
server's shutdown path, and `flush()` at the end of a serverless handler.
- **A hiding page sends at most about 60 KB**, the rest waits for the page to come back.
- **The ingest key is public on the web.** Anyone who reads your page can send events to the
project too, so don't treat incoming events as trusted input. Those events aren't
[verified](/concepts/verification); events from Node with a server key are.
# Java and Kotlin (JVM)
> Structured logs from your Java and Kotlin services (Spring, Ktor, plain JVM), with a Logback appender. No dependencies beyond the Kotlin standard library.
Source: https://docs.lyrelog.com/sdks/jvm
The JVM SDK needs Java 11 or later. It is written in Kotlin and every function can be called
from Java. It runs the same engine as the [Android SDK](/sdks/android) (`lyrelog-core`) and
has no other dependency beyond the Kotlin standard library. SLF4J and Logback records can flow in
through a separate, optional appender.
Internal preview: this package isn't published yet. Until it is, Gradle and Maven can't fetch
`com.lyrelog:lyrelog-jvm`: it isn't on Maven Central, and the repository is private and has no
release yet.
## Install [#install]
From Maven Central. With Gradle, in `build.gradle.kts`:
```kotlin
dependencies {
implementation("com.lyrelog:lyrelog-jvm:0.1.0")
// Optional: SLF4J and Logback records (Spring Boot's default logging) to Lyrelog.
implementation("com.lyrelog:lyrelog-jvm-logback:0.1.0")
}
```
With Maven, in `pom.xml`:
```xml
com.lyrelog
lyrelog-jvm
0.1.0
com.lyrelog
lyrelog-jvm-logback
0.1.0
```
The appender doesn't bring Logback: it uses the one your application already has (1.3 or later).
## Start [#start]
Once, as early as possible: in `main`, before the framework starts.
```kotlin
import com.lyrelog.Configuration
import com.lyrelog.Lyrelog
fun main(args: Array) {
Lyrelog.start(Configuration(
apiKey = System.getenv("LYRELOG_KEY"), // a server key, lyr_srv_...
platform = "api",
))
runApplication(*args) // or embeddedServer(Netty, ...) in Ktor
}
```
In Java:
```java
import com.lyrelog.Configuration;
import com.lyrelog.Lyrelog;
public static void main(String[] args) {
Lyrelog.start(Configuration.builder(System.getenv("LYRELOG_KEY")).platform("api").build());
SpringApplication.run(OrdersApplication.class, args);
}
```
Use a server key, `lyr_srv_...`, from the project's **API keys** page (**Send events from a
server**). It is a secret: keep it in your server's environment, never in an app or a web page.
Its events are [verified](/concepts/verification), and one address has no daily share of
the month. An ingest key, `lyr_ing_...`, works too, but its events aren't verified.
`start` returns `true` when it started Lyrelog. A second call while it runs is ignored and
returns `false`. A `null` or blank key starts nothing and returns `false`, and every other call
then does nothing, so a missing environment variable in development or tests doesn't stop the
service. Events logged before `start` are ignored. `start` never throws.
Events go to `https://ingest.lyrelog.com`. Pass `endpoint` only to send them somewhere else. It
is the base URL (a pasted `.../v1/events:batch` path is stripped) and must be `https://`, or
`http://` for `localhost`, `127.0.0.1` or `::1`. Any other endpoint is refused: nothing is sent,
and the SDK says so once on its [diagnostics](#delivery-and-limits).
## Log events [#log-events]
One function per level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`, or
`Lyrelog.log(level, message, ...)`.
```kotlin
Lyrelog.info("checkout_done", attrs = mapOf("plan" to "pro", "latency_ms" to 412))
Lyrelog.error("payment_failed",
category = "billing",
attrs = mapOf("code" to "card_declined"),
payload = mapOf("response" to body),
)
```
Attributes can be strings, numbers, booleans, `null`, lists (sent as strings) and nested maps up
to 4 levels. The payload is any map, list or value. A log call never blocks and never throws: it
copies the event and returns. After `close`, log calls do nothing.
## Loggers for each area [#loggers-for-each-area]
```kotlin
val billing = Lyrelog.logger("billing")
billing.warning("invoice_retry", mapOf("attempt" to 2))
```
A logger is cheap to make and keep (a field, a companion object). It logs into whatever is
running when it is called, so it can be made before `start`.
## Users [#users]
A server handles many people at once. Set the user on the event, or for the work of one request:
```kotlin
Lyrelog.info("checkout_done", user = customerId) // for this event only
Lyrelog.userScope(customerId).use { // for everything logged on this thread
handle(request) // until the scope is closed
}
Lyrelog.setUser("u_123") // every following event, every thread
Lyrelog.setUser(null) // clear it
```
The event's own `user` wins over the scope's, and the scope's over `setUser`. A scope is
thread-local: in Java, open it with try-with-resources in a servlet filter (as in
[the request filter below](#a-spring-request-filter)). Coroutines and reactive code (Ktor,
WebFlux) hop between threads, so pass `user` on each event there instead. Use your own ids, not
email addresses.
## The Logback appender [#the-logback-appender]
With `lyrelog-jvm-logback`, every record your loggers write through SLF4J or Logback can also go
to Lyrelog. Add the appender in `logback.xml` (in Spring Boot, `logback-spring.xml`):
```xml
```
The appender forwards to the running `Lyrelog`, started in code as above. Or let it start
Lyrelog itself, so the service needs no code at all; it then closes Lyrelog when Logback stops:
```xml
${LYRELOG_KEY}
api
```
Records logged before Lyrelog starts are ignored, so start it before your framework logs what you
want to keep. To keep printing to the console as well, keep your console appender beside this one.
```java
private static final org.slf4j.Logger log = LoggerFactory.getLogger(Invoices.class);
MDC.put("user_id", customerId); // the event's user
log.info("Order {} shipped", orderId);
log.atWarn().addKeyValue("attempt", 2).log("invoice_retry");
log.error("charge_failed", e);
```
| SLF4J and Logback | Lyrelog |
|---|---|
| Logger name (`com.example.billing.Invoices`) | `category`, unless the appender has a `` or the record a `category` key |
| `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` | `trace`, `debug`, `info`, `warning`, `error` |
| The formatted message | `message`; with arguments, the pattern goes to `attrs.msg_template` to group by |
| MDC entries, and SLF4J 2 key-value pairs (`addKeyValue`) | `attrs`, except `user_id` (the event's user) and `category`. `false` leaves the MDC out |
| The exception | `attrs.error_type`, `attrs.error_message` and `payload.exception` (frames, causes) |
| The record's time | The event's time |
Lyrelog's own minimum level still applies: `trace` records are dropped unless `minimumLevel` is
`Level.TRACE`. The appender ignores records from `com.lyrelog` loggers and from the SDK's own
threads, so it can never loop. There is no appender for Log4j 2 or `java.util.logging`. For
events you want to chart, prefer direct calls with a stable name: a formatted message is prose.
## A Spring request filter [#a-spring-request-filter]
There is no built-in filter. This one records every request as `http_request_served` in the
`http` area, at info, warning for a 4xx and error for a 5xx, with the route pattern rather than
the path, so ids don't explode the cardinality. It also sets the request's user for everything
logged while it is handled:
```java
import com.lyrelog.Level;
import com.lyrelog.Lyrelog;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Map;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import org.springframework.web.servlet.HandlerMapping;
@Component
public class LyrelogRequests extends OncePerRequestFilter {
private final com.lyrelog.Logger http = Lyrelog.logger("http");
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws ServletException, IOException {
try (Lyrelog.UserScope user = Lyrelog.userScope(currentUserId(request))) { // your own id, or null
long start = System.nanoTime();
int status = 500; // when the handler throws, Spring writes the error page later
try {
chain.doFilter(request, response);
status = response.getStatus();
} finally {
Object route = request.getAttribute(HandlerMapping.BEST_MATCHING_PATTERN_ATTRIBUTE);
Level level = status >= 500 ? Level.ERROR : status >= 400 ? Level.WARNING : Level.INFO;
http.log(level, "http_request_served", Map.of(
"method", request.getMethod(),
"route", route != null ? route.toString() : "unmatched", // /orders/{id}, not the id
"status", status,
"duration_ms", (System.nanoTime() - start) / 1_000_000));
}
}
}
}
```
Spring logs an exception a handler throws on its own loggers, with the stack, so with the
Logback appender it already arrives with `error_type` and `error_message`; capturing it in the
filter too would record it twice.
## Errors [#errors]
```kotlin
try {
charge(order)
} catch (e: PaymentException) {
Lyrelog.captureError(e, category = "billing", attrs = mapOf("order_id" to order.id))
}
```
The event is `exception`, level `error`, with `error_type` (the class name) and `error_message`
in the attributes and, in the payload, the description, up to 60 frames, the causes (up to 8, 20
frames each) and the suppressed exceptions. Your attributes are added; those two win. `level`
changes the level and `user` sets the event's user. `logger.captureError(e)` uses the logger's
category.
## Uncaught exceptions [#uncaught-exceptions]
Off by default. With `captureUncaught = true`, an exception that no code caught, on any thread,
is recorded as `exception` with `handled: false`, `mechanism: uncaught_exception` and the
thread's name in `thread`. Then the handler that was there before runs (or the JVM's usual
printout). When that thread was the last one, the shutdown hook sends the event before the JVM
exits.
```kotlin
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"), captureUncaught = true))
```
Frameworks catch the exceptions of a request themselves and log them: those arrive through the
Logback appender. An exception in a task given to an `ExecutorService` with `submit` goes to its
`Future`, not to this handler.
## Environments and platform [#environments-and-platform]
`environment` comes from the `LYRELOG_ENVIRONMENT` environment variable, else `production`.
`platform` is `jvm`. Set either in the configuration:
```kotlin
Lyrelog.start(Configuration(apiKey = key, environment = "staging", platform = "worker"))
```
Any name works: lowercase letters, digits, `-` and `_`, up to 32. Other text in the configuration
is cleaned for you (`Staging EU` is `staging-eu`); an invalid `$LYRELOG_ENVIRONMENT` is reported
once and replaced by `production`, so a typo in a deploy never stops a service.
`release` (`resource.app_version`) defaults to the `Implementation-Version` of the jar the JVM
was started with (`java -jar orders.jar`), and `appId`
(`resource.app_id`) to its `Implementation-Title`, else the jar's file name, else the main class.
Set them when that isn't what you want.
## Consent [#consent]
Consent is for apps that run on someone's device. A server SDK sends what it is given; there is
no consent option.
## Flush and stop [#flush-and-stop]
```kotlin
Lyrelog.flush() // send what's queued now, waiting up to 5 s; true when it finished
Lyrelog.flushInBackground() // the same, without waiting
Lyrelog.close() // send what's left (up to closeTimeoutMillis), then stop
```
You rarely need any of them: the SDK sends every 5 s, and a JVM shutdown hook closes it when the
JVM exits normally (the end of `main`, `System.exit`, `SIGTERM` and Ctrl-C). `kill -9` skips the
hook. Turn the hook off with `shutdownHook = false` and call `close` yourself.
`flush` respects a `Retry-After` the server asked for: it doesn't send sooner. After `close`,
`start` can be called again.
In a serverless function (AWS Lambda), call `Lyrelog.flush()` before the handler returns: the
runtime may freeze the process before the next send.
## Where events wait [#where-events-wait]
Events are written to a queue directory, one file per batch, and a batch leaves it only once the
server has taken it.
- **By default**, a new directory under `java.io.tmpdir` for this process, deleted on `close`.
What wasn't sent by then is lost, as with an in-memory queue.
- **With `storageDirectory`**, a directory of your own: what wasn't sent (the server was
unreachable, or asked to wait) stays there and goes out after the next `start`. One process at a
time: the directory is locked, and a second process that finds it locked queues in a temporary
directory instead, and says so once.
Both are capped at 20 MB and 7 days, oldest first (`maxDiskBytes`, `maxEventAgeMillis`).
## In development and tests [#in-development-and-tests]
Leave the key out: `Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY")))` starts
nothing when the variable isn't set, and every call does nothing, so tests and a laptop without a
key run the same code. The Logback appender does nothing either while Lyrelog isn't running.
To see what a test logs, point `endpoint` at a local HTTP server (plain `http://` is allowed for
loopback addresses) and read the batches it receives: gzipped NDJSON, one event per line, as on
the [HTTP API](/http-api) page.
## From Java [#from-java]
Every function on `Lyrelog` is static from Java, with overloads for the optional arguments, and
`Configuration` has a builder:
```java
Lyrelog.start(Configuration.builder(System.getenv("LYRELOG_KEY"))
.platform("api")
.environment("staging")
.captureUncaught(true)
.build());
Lyrelog.info("checkout_done");
Lyrelog.info("checkout_done", "billing", Map.of("plan", "pro"));
Lyrelog.captureError(e, "billing");
try (Lyrelog.UserScope scope = Lyrelog.userScope(customerId)) {
Lyrelog.logger("billing").warning("invoice_retry", Map.of("attempt", 2));
}
```
`new Configuration(key)` works too, and a logger's functions have overloads, so trailing
arguments can be left out.
## Verified events [#verified-events]
A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).
Send with a server key, `lyr_srv_...`. Every event it sends is verified (`verified_by` is
`server`) and doesn't count toward the
[daily share of one address](/concepts/verification#the-daily-share-of-one-address). An owner
makes it on the project's **API keys** page, **Send events from a server**, after a recent sign-in
(within 10 minutes), and it is shown once. It is a secret: keep it out of the repository and read
it from the server's environment or secret store.
```kotlin
Lyrelog.start(Configuration(apiKey = System.getenv("LYRELOG_KEY"))) // lyr_srv_..., set in the server's environment
```
To check, open the [explorer](/dashboard/explorer): in **Filter**, pick **Verified by** and
**Server key** (the other values are **App Attest** and **Not verified**). An opened event says it under
**Context**, in its **Sender** line: **Verified, server key**, or **Not verified, public key**.
Events sent with an ingest key, `lyr_ing_...`, or a full-access key, `lyr_adm_...`, arrive
unverified: anyone holding a public key could have sent the same, and they count toward the daily
share. A verified event proves who sent it, not that what it says is true.
See [Verified events](/concepts/verification) for who verifies what and the daily share.
## Configuration [#configuration]
| Option | Default | Meaning |
|---|---|---|
| `apiKey` | required | The project's server key (`lyr_srv_...`), or an ingest key. `null` or blank: nothing starts |
| `endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is stripped. `https` only, `http` only for localhost |
| `environment` | `$LYRELOG_ENVIRONMENT`, else `production` | Any valid name |
| `platform` | `jvm` | `api`, `worker`... |
| `release` | the started jar's `Implementation-Version` | Sent as `resource.app_version` |
| `appId` | the started jar's `Implementation-Title` or file name, else the main class | Sent as `resource.app_id`: the service name |
| `minimumLevel` | `Level.DEBUG` | Events below it are dropped before queueing |
| `flushIntervalMillis` | 5 s | How often the background thread sends |
| `maxBatchBytes` | 512 KiB | A batch closes at whichever limit comes first (kept within 4 MiB) |
| `maxBatchEvents` | 500 | At most 2,000 |
| `maxQueue` | 10,000 | Events waiting to be written; past it the oldest is dropped and counted |
| `maxDiskBytes` | 20 MB | Cap on the queue directory, oldest first |
| `maxEventAgeMillis` | 7 days | Older queued events are dropped |
| `redactedKeys` | `null`: `DEFAULT_REDACTED_KEYS` | Key names to redact; your list replaces the defaults, an empty list turns it off |
| `storageDirectory` | a temporary directory per process | Where the queue lives; see [Where events wait](#where-events-wait) |
| `captureUncaught` | `false` | Record [uncaught exceptions](#uncaught-exceptions) |
| `shutdownHook` | `true` | Close when the JVM shuts down |
| `closeTimeoutMillis` | 5 s | How long closing waits for the last send |
| `diagnostics` | standard error | Receives the SDK's own messages (a `Consumer`). Don't point it at a logger that feeds Lyrelog |
## Delivery and limits [#delivery-and-limits]
| | |
|---|---|
| Never blocks | Logging copies the event and returns; one background writer puts it in the queue directory and never waits on the network. One background thread sends. Safe for concurrent use. |
| Batches | Up to 500 events or 512 KiB per request, gzipped, every `flushIntervalMillis`. An event over 1 MiB once encoded is dropped and counted. |
| Retries | 1 s doubling to 5 min, with full jitter, honoring `Retry-After`; the same bytes are resent. Any other 4xx drops the batch, a 3xx (a redirect, never followed) drops it, and a refused key (`401`, `403`) stops sending until the process restarts and keeps the events. A batch the server keeps failing while others go through goes to the back, then is dropped. |
| Monthly quota | When a Free organization has used its month's events, the server answers `429`. Events stay in the queue and go out once the server takes them again, within the 20 MB and 7 day caps. The SDK prints one warning on its diagnostics, and again only after a batch has been accepted in between. |
| Drops are visible | Events lost to the caps become one `lyrelog_events_dropped` warning (area `lyrelog`) with the count. |
| Its own problems | A wrong endpoint, a `404`, a refused key, rejected lines or an endpoint that doesn't answer are said once per process on `diagnostics` (standard error by default), each line starting with `lyrelog: `. |
| Context | `os_name` and `os_version` (the JVM's `os.name` and `os.version`), the app id, release, environment and platform, an install id per process and one session id per process. |
| Secrets | Values under keys whose name is or ends with `authorization`, `cookie`, `password`, `token`, `secret`, `apikey` and the rest of the [shared list](/sdks#what-every-sdk-does-for-you) become `"[redacted]"`, at any depth, before anything is cut. |
| Limits | Long strings cut on a character boundary, extra attributes counted in `lyrelog_dropped_attrs`, payloads over 64 KiB summarized as `{"lyrelog_truncated": true, "bytes": N, "preview": "..."}`. |
| The key | Printing a `Configuration` hides it. |
Change the redaction list with `redactedKeys`: your list replaces the defaults, and an empty list
turns redaction off. To add to it:
```kotlin
Lyrelog.start(Configuration(
apiKey = System.getenv("LYRELOG_KEY"),
redactedKeys = Configuration.DEFAULT_REDACTED_KEYS + "card_number",
))
```
# Python
> Structured logs from your Python services, with a logging handler. Standard library only.
Source: https://docs.lyrelog.com/sdks/python
The `lyrelog` package needs Python 3.11 or later and has no dependencies.
Internal preview: this package isn't published yet. Until it is, `uv add lyrelog` fails: there
is no package on PyPI.
## Install [#install]
```bash
uv add lyrelog
```
## Start [#start]
Once, at startup. `lyrelog.init` starts the default client (flushing and replacing any earlier
one) and returns it; the module-level functions use it.
```python
import lyrelog
lyrelog.init(
api_key="lyr_srv_...", # a server key: it can append events, never read them
release="2.0.1", # goes to resource.app_version
app_id="orders-api",
)
```
Use a server key, `lyr_srv_...`, from the project's **API keys** page (**Send events from a
server**). It is a secret: keep it in your server's environment, never in an app or a web page.
Its events are [verified](/concepts/verification), and one address has no daily share of
the month. An ingest key, `lyr_ing_...`, works too, but its events aren't verified.
Events go to `https://ingest.lyrelog.com`. Pass `endpoint` only to send them somewhere else. It
is the base URL (a pasted `.../v1/events:batch` path is stripped) and must be `https://`, or
`http://` for localhost.
An empty `api_key` gives a client that accepts events and sends nothing, so a
missing environment variable in development doesn't crash the app. A missing key or a bad
endpoint is reported once as a warning on the `lyrelog` logger.
`lyrelog.Client(endpoint, api_key, ...)` is the same without the module-level default, for a
second project or for tests: every function below is a method on it. `lyrelog.get_client()`
returns the default client, or `None` before `init`.
## Log events [#log-events]
One function per level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`, or
`lyrelog.log(level, message, ...)`.
```python
lyrelog.info("checkout_done", attrs={"items": 3, "latency_ms": 412})
lyrelog.error("payment_declined", category="checkout", attrs={"code": 51}, payload={"response": raw})
```
A log call never blocks and never raises: anything odd you pass (objects, NaN, cycles) is turned
into something valid. After `shutdown()`, log calls do nothing.
## Loggers for each area [#loggers-for-each-area]
```python
billing = lyrelog.logger("billing")
billing.warning("refund_denied", attrs={"order_id": order.id}, user_id=order.user_id)
```
A logger follows the default client at call time, so you can make it at import, before `init`.
## Users [#users]
```python
lyrelog.set_user("u_123") # attached to every following event, process-wide
lyrelog.info("checkout_done", user_id=request_user) # for this event only
```
A server handles many people at once, so prefer `user_id=` on each call to `set_user`.
## The logging handler [#the-logging-handler]
The quickest way is `install_logging`, which adds one `LoggingHandler` to the root logger (and,
with `uvicorn=True`, the default, to `uvicorn` and `uvicorn.error`) and lowers the root logger to
`level` if it is above it, so `INFO` records get through. Calling it again replaces the earlier
handler, and `uninstall_logging()` removes it; `uvicorn.access` is left out (record requests in a
middleware instead).
```python
import logging
import lyrelog
lyrelog.install_logging(logging.INFO)
```
To add the handler yourself, remember that the root logger stops at `WARNING` by default: a
handler set to `INFO` gets nothing below `WARNING` until the root logger lets it through.
```python
import logging
import lyrelog
logging.basicConfig(level=logging.INFO) # or logging.getLogger().setLevel(logging.INFO)
logging.getLogger().addHandler(lyrelog.LoggingHandler(level=logging.INFO))
log = logging.getLogger("app.orders")
log.info("order %s shipped", order_id, extra={"items": 3, "user_id": uid})
log.exception("email_failed") # inside an except: the traceback goes in the payload
```
| `logging` | Lyrelog |
|---|---|
| Logger name (`app.matches`, `uvicorn.error`) | `category` |
| `DEBUG` ... `CRITICAL` | The same; below `DEBUG` is `trace`, between `INFO` and `WARNING` is `notice` |
| The formatted message | `message`; with arguments, the template goes to `attrs.msg_template` to group by |
| `extra=` fields | `attrs`, except `user_id` (the event's user) and `payload` (kept as `payload.data`) |
| `exc_info` | `payload.exception` and `attrs.error_type`, `attrs.error_message` |
| File, line, function | `payload.source` |
The handler never forwards the SDK's own logger, so it can't loop. That logger is named
`lyrelog`: to see what the SDK itself reports (a refused key, a wrong endpoint, dropped events),
give it a handler, for example `logging.getLogger("lyrelog").setLevel(logging.DEBUG)` with
`basicConfig`. For events you want to chart,
prefer direct calls with a stable name: a formatted message is prose.
## FastAPI [#fastapi]
```python
import logging
import os
import time
import lyrelog
from fastapi import FastAPI, Request
lyrelog.init(
api_key="lyr_srv_...", # a server key, or read it from your own settings
platform="api", # instead of "python", to tell it apart from a worker
release=os.environ.get("GIT_SHA"),
app_id="orders-api",
)
# uvicorn.error carries the tracebacks of unhandled exceptions. Uvicorn's loggers don't
# propagate to the root logger (propagate=False), so a root handler never sees them:
# uvicorn=True attaches the handler to them too. Uvicorn replaces its loggers' handlers when
# it applies its config, so call this after that: here, at import of the app module that
# `uvicorn app:app` runs, or in the app's lifespan startup.
lyrelog.install_logging(logging.INFO, uvicorn=True)
app = FastAPI()
http = lyrelog.logger("http")
@app.middleware("http")
async def record_request(request: Request, call_next):
start = time.perf_counter()
status = 500
try:
response = await call_next(request)
status = response.status_code
return response
finally:
route = request.scope.get("route") # set by the router once it matched
http.log(
"error" if status >= 500 else "warning" if status >= 400 else "info",
"http_request_served",
attrs={
"method": request.method,
"route": getattr(route, "path", "unmatched"), # /matches/{match_id}, not the id
"status": status,
"duration_ms": round((time.perf_counter() - start) * 1000, 1),
},
)
```
The route template keeps ids out of the attribute, so the dashboard can count by route. The
middleware doesn't capture unhandled exceptions itself: uvicorn logs each one with its traceback
on `uvicorn.error`, and `install_logging` forwards that record with `error_type`,
`error_message` and the traceback, so capturing it here too would record it twice. With gunicorn
or `uvicorn --workers`, each worker process gets its own sender.
## Django [#django]
Start the client once, in `settings.py` or your `AppConfig.ready()`, and send `logging` records
through Django's `LOGGING` setting:
```python
# settings.py
import lyrelog
lyrelog.init(api_key="lyr_srv_...", platform="api", app_id="shop")
LOGGING = {
"version": 1,
"disable_existing_loggers": False,
"handlers": {"lyrelog": {"class": "lyrelog.LoggingHandler", "level": "INFO"}},
"root": {"handlers": ["lyrelog"], "level": "INFO"},
"loggers": {
# Django's request errors carry the traceback of a 500.
"django.request": {"handlers": ["lyrelog"], "level": "WARNING", "propagate": False},
},
}
```
## A worker or a script [#a-worker-or-a-script]
A job that runs for many people sets the user on each event, and stops the client before it
ends:
```python
import os
import time
import lyrelog
lyrelog.init(api_key=os.environ.get("LYRELOG_KEY", ""), platform="worker", app_id="digest")
jobs = lyrelog.logger("jobs")
def send_digest(user):
started = time.perf_counter()
try:
deliver(user)
except Exception:
jobs.capture_exception(attrs={"job": "digest"}, user_id=user.id)
return
jobs.info("digest_sent", attrs={"duration_ms": round((time.perf_counter() - started) * 1000)},
user_id=user.id)
if __name__ == "__main__":
for user in due_users():
send_digest(user)
lyrelog.shutdown() # sends what's left, up to 5 s
```
## Serverless and short scripts [#serverless-and-short-scripts]
The worker sends every 5 s and once more at exit (`atexit`). A function that is frozen between
requests (AWS Lambda, Cloud Functions) may never reach either: call `lyrelog.flush()` before
returning, and check what it returns if you need to know.
```python
def handler(event, context):
try:
return process(event)
finally:
lyrelog.flush(timeout=2)
```
`atexit` doesn't run after `os._exit()`, or when the process gets `SIGTERM` without a handler.
Uvicorn and gunicorn handle `SIGTERM` and exit normally; in your own long-running process, stop
the client in a handler:
```python
import signal
import sys
import lyrelog
def on_sigterm(signum, frame):
lyrelog.shutdown(timeout=2)
sys.exit(0)
signal.signal(signal.SIGTERM, on_sigterm)
```
## Uncaught exceptions [#uncaught-exceptions]
The SDK doesn't install a hook for uncaught exceptions. To record them, set one yourself, for
the main thread and for other threads:
```python
import sys
import threading
import lyrelog
def report(exc_type, exc, tb):
lyrelog.capture_exception(exc, level="critical")
lyrelog.flush(timeout=2)
sys.__excepthook__(exc_type, exc, tb)
def report_thread(args):
if args.exc_value is not None and not issubclass(args.exc_type, SystemExit):
name = args.thread.name if args.thread else ""
lyrelog.capture_exception(args.exc_value, attrs={"thread": name}, level="critical")
threading.__excepthook__(args)
sys.excepthook = report
threading.excepthook = report_thread
```
Frameworks catch exceptions inside requests themselves: for those, use the middleware above or
the framework's logger.
## Exceptions [#exceptions]
```python
try:
sync()
except Exception:
lyrelog.capture_exception(category="jobs")
```
With no argument it captures the exception being handled; pass one to capture another. It logs
`exception` at `error` with `attrs.error_type` and `attrs.error_message` (the same in every SDK),
and the type, message and traceback in the payload. `message=` and `level=` change the event's
name and level, and `user_id=` sets its user. A logger's `capture_exception` uses its category.
## Environments and platform [#environments-and-platform]
`environment` comes from the `LYRELOG_ENVIRONMENT` environment variable, else `production`.
`platform` is `python`. Set either in `init`:
```python
lyrelog.init(api_key=..., environment="staging", platform="worker")
```
Any name works: lowercase letters, digits, `-` and `_`, up to 32. Other text is normalized for you.
## Consent [#consent]
Consent is for apps that run on someone's device. A server SDK sends what it is given; there is
no consent option.
## Redacting and filtering [#redacting-and-filtering]
A value becomes `"[redacted]"`, in attributes and the payload, when its key name, lowercased and
without `-`, `_`, `.` or spaces, is or ends with one of `authorization`, `cookie`, `password`,
`passwd`, `secret`, `token`, `apikey`, `privatekey`, `credential`, `credentials`, `accesskey` or
`signature`. So `X-Api-Key`, `csrf_token`, `Set-Cookie` and `user_token` are redacted;
`token_count` and `max_tokens` aren't.
`redact_keys=[...]` replaces that list with yours (matched the same way), and `redact_keys=[]`
turns redaction off. To keep the defaults and add one, pass
`redact_keys=[*lyrelog.DEFAULT_REDACT_KEYS, "card_number"]`.
To change or drop events yourself, pass `before_send` to `init`: a function that gets each event
and returns it, changed or not, or `None` to drop it.
```python
def before_send(event):
if event["message"] == "health_check":
return None
return event
lyrelog.init(api_key="lyr_srv_...", before_send=before_send)
```
## Flush and stop [#flush-and-stop]
```python
sent = lyrelog.flush() # rarely needed: it sends every 5 s and at exit
lyrelog.shutdown() # also runs at exit: one last attempt, up to 5 s
```
`flush` waits until everything logged before the call has been sent, up to its `timeout` (5 s
by default), and returns `True` if the queue drained, `False` if events are still waiting (the
server asked to wait with `Retry-After`, or it couldn't be reached) or were lost. Each request to
the server times out after 15 s.
`client.stats()` (on the client `init` returns) reports `queued`, `dropped` (queue full),
`delivered`, `rejected` (lines the server refused), `discarded` (batches dropped after a 4xx or
3xx), `filtered` (dropped by `before_send`), `failed` (events that couldn't be shaped, or whose
`before_send` raised), `reentrant` (logged from inside the SDK, for example a signal handler) and
`disabled` (a refused key, no key or a bad endpoint).
## In development and tests [#in-development-and-tests]
Leave `api_key` empty: the client accepts events, sends nothing and warns once on the `lyrelog`
logger.
```python
lyrelog.init(api_key=os.environ.get("LYRELOG_KEY", ""))
```
Without `init`, the module-level functions and loggers do nothing.
## Verified events [#verified-events]
A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).
Send with a server key, `lyr_srv_...`. Every event it sends is verified (`verified_by` is
`server`) and doesn't count toward the
[daily share of one address](/concepts/verification#the-daily-share-of-one-address). An owner
makes it on the project's **API keys** page, **Send events from a server**, after a recent sign-in
(within 10 minutes), and it is shown once. It is a secret: keep it out of the repository and read
it from the server's environment or secret store.
```python
import os
lyrelog.init(api_key=os.environ["LYRELOG_KEY"]) # lyr_srv_..., set in the server's environment
```
To check, open the [explorer](/dashboard/explorer): in **Filter**, pick **Verified by** and
**Server key** (the other values are **App Attest** and **Not verified**). An opened event says it under
**Context**, in its **Sender** line: **Verified, server key**, or **Not verified, public key**.
Events sent with an ingest key, `lyr_ing_...`, or a full-access key, `lyr_adm_...`, arrive
unverified: anyone holding a public key could have sent the same, and they count toward the daily
share. A verified event proves who sent it, not that what it says is true.
See [Verified events](/concepts/verification) for who verifies what and the daily share.
## Configuration [#configuration]
| Option | Default | Meaning |
|---|---|---|
| `endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is stripped |
| `api_key` | required | The project's server key (`lyr_srv_...`), or an ingest key. Empty: nothing is sent |
| `environment` | `LYRELOG_ENVIRONMENT`, else `production` | Any valid name |
| `platform` | `python` | `api`, `worker`... |
| `release` | none | `resource.app_version` |
| `app_id` | none | `resource.app_id`: the service name |
| `minimum_level` | `"debug"` | Events below it are dropped before queueing |
| `flush_interval` | `5.0` s | How often the worker sends |
| `max_queue` | `10_000` | Oldest dropped beyond it |
| `max_queue_bytes` | 16 MiB | The same cap, in bytes |
| `redact_keys` | `DEFAULT_REDACT_KEYS` | The key names to redact; replaces the defaults |
| `before_send` | none | Change an event, or return `None` to drop it |
| `session_timeout` | 30 min | Idle time that starts a new session. Only on `lyrelog.Client`, not `init` |
## Delivery and limits [#delivery-and-limits]
| | |
|---|---|
| Batches | Up to 500 events or 512 KiB, gzip. A full batch goes out at once, otherwise every `flush_interval`. An event over 1 MiB is dropped and counted. |
| Retries | 1 s doubling to 5 min with equal jitter, honoring `Retry-After` (at most an hour); the same bytes are resent. Any other 4xx drops the batch; a 3xx drops it with a warning (redirects aren't followed). A refused key (`401`, `403`) stops sending until the process restarts and keeps the events in memory. |
| Monthly quota | When a Free organization has used its month's events, the server answers `429`. The events stay in memory and go out once the server takes them again, up to `max_queue`. The SDK logs one warning on the `lyrelog` logger with the server's message, and warns again only after a batch has been accepted. |
| Caps | Past `max_queue` the oldest go, and a `lyrelog_events_dropped` warning with the count goes out with the next batch. |
| Threads and forks | Thread-safe. After `os.fork` the child gets a fresh queue, worker, install and session. |
| Context | `os_name` (`platform.system()`), `os_version` (`platform.release()`), `device_model` (`platform.machine()`), an install id per process, and a session id per process that changes after 30 minutes without an event. |
| Limits | Fitted before queueing: nested objects past 4 levels become a JSON string, dots in attribute names become `_`, a payload over 64 KiB becomes `{"lyrelog_truncated": true, "bytes": N, "preview": "..."}`, tracebacks keep their last 48 KiB. |
# React Native
> Structured logs, JavaScript errors and crashes from your React Native app, over the Swift and Android SDKs.
Source: https://docs.lyrelog.com/sdks/react-native
The React Native SDK is a thin TurboModule over the [Swift](/sdks/swift) and
[Android](/sdks/android) SDKs. The native SDKs keep the queue on disk, send in batches,
retry, keep sessions and report native crashes. This package adds what only JavaScript sees:
uncaught errors, unhandled promise rejections, React render errors and React Navigation screens.
It needs React Native 0.80 or later with the New Architecture, and React 19. Apps run on iOS 16
or later and Android 7.0 (API 24) or later.
Internal preview: this package isn't published yet. Until it is, `@lyrelog/react-native` isn't
on npm, and the native SDKs it builds on aren't published either.
## Install [#install]
```sh
pnpm add @lyrelog/react-native
cd ios && pod install
```
On iOS the pod brings the `Lyrelog` Swift package through Swift Package Manager. Set your app's
deployment target (and the `platform :ios` line in the Podfile) to 16.0 or later. On Android,
Gradle fetches `com.lyrelog:lyrelog-android` from Maven Central, which adds the `INTERNET`
permission.
## Start [#start]
Start once, as early as possible, in `index.js` before `AppRegistry`. A second call keeps the
first configuration. Events logged before `init` are ignored, but `setUser` and `setConsent`
called before `init` are kept and applied when it runs.
```ts
import { AppRegistry } from "react-native";
import { Lyrelog } from "@lyrelog/react-native";
import App from "./src/App";
Lyrelog.init({
apiKey: "lyr_ing_...", // ingest-only: it can append events, never read them
});
AppRegistry.registerComponent("main", () => App);
```
Events go to `https://ingest.lyrelog.com`. Pass `endpoint` only to send them somewhere else. It
must be `https`; plain `http` works only for `localhost`, `127.0.0.1` or `::1` (the iOS
simulator), and on the Android emulator for `10.0.2.2`.
Nothing in the SDK throws into your app. In a development build, a missing key or a missing
native module (the app wasn't rebuilt after installing) is reported once with `console.warn`.
## Log events [#log-events]
One function per level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`, or
`log(level, message, options)`.
```ts
Lyrelog.info("checkout_done", { attrs: { items: 3, latency_ms: ms } });
Lyrelog.error("payment_declined", {
category: "checkout",
attrs: { code: 51 },
payload: { response },
});
```
Attributes are small fields to filter and chart by: strings, numbers, booleans, `null`, arrays
and nested objects up to 4 levels. The payload is any JSON, for the detail you only read when
you open one event. `minimumLevel` (default `debug`) drops lower levels before they cross to
native code.
## Loggers for each area [#loggers-for-each-area]
A logger stamps its `category` on every event. It has every level, plus `log` and
`captureException`.
```ts
const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 2 } });
```
## Users [#users]
```ts
Lyrelog.setUser(playerId); // attached to every following event
Lyrelog.setUser(null); // on sign-out
```
`Lyrelog.sessionId` gives the current session id, for example to show in a support screen. The
user id isn't saved between launches: call `setUser` again on each launch.
## Screens [#screens]
With React Navigation, spread `trackNavigation` on the container:
```tsx
import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import { trackNavigation } from "@lyrelog/react-native";
const navigationRef = createNavigationContainerRef();
export default function App() {
return (
{/* your navigators */}
);
}
```
Each screen shown logs `screen_viewed` (area `navigation`) with `screen`, `previous_screen` and
`seconds_on_previous`, and every following event is tagged with a `screen` attribute. The name is
the route's; pass `name: (route) => ...` to choose another, or return `undefined` to skip a
route. Your own `onReady` and `onStateChange` go in the options and run after Lyrelog's.
Without React Navigation, call `Lyrelog.screen("Settings")`, or `useLyrelogScreen("Settings")`
in the screen's component. Calling `screen` again with the same name logs nothing. Turn the
tagging off with `attachScreen: false`.
## Errors you catch [#errors-you-catch]
```ts
try {
await store.purchase(product);
} catch (error) {
Lyrelog.captureException(error, { category: "store" });
}
```
It sends the `exception` event every SDK sends: level `error`, the attributes `error_type` and
`error_message`, and a payload with the name, message, stack and up to 3 causes
(`error.cause`). `attrs` adds your own; `level` changes the level. Anything can be thrown in
JavaScript: a string or an object is recorded too.
Stacks are as Hermes reports them. In a release build they point into the bundle: keep the
build's source map to read them.
## Errors nobody caught [#errors-nobody-caught]
With `captureErrors` (on by default), the SDK hooks into React Native's error handling:
| What happens | Event | Level, area | `mechanism` |
|---|---|---|---|
| A fatal JavaScript error, such as a throw in a timer or an event handler | `app_crashed` | critical, `diagnostics` | `js_fatal` |
| A render error no error boundary caught | `app_crashed` | critical, `diagnostics` | `react_render` |
| A non-fatal error reported to `ErrorUtils` | `exception`, `handled: false` | error | `js_error` |
| An unhandled promise rejection | `exception`, `handled: false` | error | `unhandled_rejection` |
A fatal error is written to disk before the app goes, waiting up to 1.5 seconds, and is sent
then if it can be, otherwise on the next launch. It is `app_crashed` in the `diagnostics` area,
like the native crash reports, so JavaScript and native crashes sit together in the dashboard.
Each error is recorded once. Uncaught errors that aren't fatal are capped at 10 a minute, and
the same one at most once every 10 seconds; `Lyrelog.skippedErrors` counts what was left out.
The handlers that were there before still run: the red box and LogBox in development, the
crash in release.
## Error boundaries [#error-boundaries]
```tsx
import { LyrelogErrorBoundary } from "@lyrelog/react-native";
}
>
```
A render error below it is recorded as `exception` with `mechanism: error_boundary` and React's
component stack (`component_stack` in the payload), and `fallback` is shown instead. `onError`
is called after it is recorded. Without a fallback it renders nothing after an error.
## Native crashes [#native-crashes]
These are the native SDKs' (`captureCrashes`, on by default), sent on the next launch in the
`diagnostics` area: uncaught JVM exceptions on Android as `app_crashed`; on iOS MetricKit's
reports, crashes as `app_crashed` and hangs as `app_hung`. See
[Android crashes](/sdks/android#crashes) and
[Swift crashes and hangs](/sdks/swift#crashes-and-hangs).
On Android, a fatal JavaScript error ends the app with a Java exception. Once the JavaScript
`app_crashed` is on disk, that exception skips the Android SDK's recorder, so the same crash
isn't reported twice.
## Environments and platform [#environments-and-platform]
The environment is the native SDK's: on iOS `development` in debug builds, `testflight` on
TestFlight, `production` otherwise; on Android `development` when the app is debuggable,
`production` otherwise. Your own debug builds send `development`, while the dashboard opens on
`production`: pick **development** in the top bar to see them.
The platform is `ios` or `android`. Override either:
```ts
Lyrelog.init({
apiKey: key,
environment: isBeta ? "beta" : undefined, // undefined = detected
});
```
Events name this package and the native SDK under it (`sdk` is
`lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0` or `lyrelog-react-native/0.1.0 lyrelog-android/0.1.0`).
## Consent [#consent]
```ts
Lyrelog.init({ apiKey: key, consent: "pending" });
// later, when the person chooses:
Lyrelog.setConsent("granted"); // sends, including what was kept while pending
Lyrelog.setConsent("denied"); // deletes everything and stops recording
```
`pending` keeps events on the device without sending them. Nothing is uploaded unless consent
is granted. Consent isn't saved between launches: store the person's choice yourself (for
example with AsyncStorage) and pass it to `init` each time.
## Attestation [#attestation]
`attest` (on by default) proves the app with App Attest on iOS and Key Attestation on Android,
so its events are stored as verified. See [Verified events](/concepts/verification).
## Options [#options]
| Option | Default | What |
|---|---|---|
| `apiKey` | | The project's ingest key, `lyr_ing_...` |
| `endpoint` | `https://ingest.lyrelog.com` | Where events go |
| `consent` | `granted` | `granted`, `pending` or `denied` |
| `environment` | detected | Any name |
| `platform` | `ios` / `android` | Which part of the product sends |
| `minimumLevel` | `debug` | Lower levels are dropped |
| `flushIntervalMs` | 15000 | How often queued events are sent in the foreground |
| `sessionTimeoutMs` | 30 minutes | A new session after this long without an event |
| `maxDiskBytes` | 20 MB | What may wait on the device; the oldest go first |
| `redactKeys` | `DEFAULT_REDACT_KEYS` | Attribute and payload keys whose values are replaced. Your list replaces the defaults; `[]` turns it off |
| `captureErrors` | true | JavaScript errors nobody caught |
| `captureCrashes` | true | Native crashes |
| `attachScreen` | true | The `screen` attribute on every event |
| `attest` | true | App Attest and Key Attestation |
| `mirrorToNativeLog` | false | Also print every event to the Xcode console or logcat |
## Flush and stop [#flush-and-stop]
Going to the background already sends, so you rarely need to.
```ts
await Lyrelog.flush(); // write everything to disk and try to send now
await Lyrelog.close(); // send what's queued (up to 2 seconds), then stop
```
After `close`, `init` can be called again.
# Swift
> Structured logs from your iOS, macOS, tvOS, watchOS or visionOS app. No dependencies.
Source: https://docs.lyrelog.com/sdks/swift
The Swift SDK needs iOS 16, macOS 13, tvOS 16, watchOS 9 or visionOS 1, and Swift 6. Some
features depend on the platform: see [Platforms](#platforms).
Internal preview: this package isn't published yet. Until it is, Xcode can't fetch it: the
repository is private and has no release yet.
## Install [#install]
Swift Package Manager. In Xcode, choose **File > Add Package Dependencies**, enter
`https://github.com/GonzaloFuentes28/lyrelog-swift` and add the product `Lyrelog` to your app's
target. In `Package.swift`:
```swift
dependencies: [
.package(url: "https://github.com/GonzaloFuentes28/lyrelog-swift", from: "0.1.0"),
],
targets: [
.target(name: "MyApp", dependencies: [.product(name: "Lyrelog", package: "lyrelog-swift")]),
]
```
## Start [#start]
Start once, as early as possible, for example in your `App`'s `init`. A second call is ignored.
Events logged before `start` are ignored too, but `setUser` and `setConsent` called before
`start` are kept and applied when it runs.
```swift
import Lyrelog
@main
struct MyApp: App {
init() {
Lyrelog.start(Configuration(
apiKey: "lyr_ing_..." // ingest-only: it can append events, never read them
))
}
var body: some Scene { WindowGroup { ContentView() } }
}
```
Events go to `https://ingest.lyrelog.com`. Pass `endpoint` only to send them somewhere else. It
is the base URL (a pasted `.../v1/events:batch` path is stripped) and must be `https`; plain
`http` works only for `localhost`, `127.0.0.1` or `::1`. With any other endpoint nothing is sent
and the events stay on the device.
## Log events [#log-events]
One function per level: `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`, or
`log(_:_:)` with a level.
```swift
Lyrelog.info("checkout_done", attrs: ["items": 3, "latency_ms": .int(ms)])
Lyrelog.error("payment_declined", category: "checkout",
attrs: ["code": 51], payload: ["response": .string(raw)])
```
Attributes and payloads are `LogValue`s. Literals work directly (`"text"`, `412`, `0.5`, `true`,
`["a", "b"]`, nested dictionaries, `nil`); for variables use the cases (`.int(ms)`,
`.string(name)`, `.double(x)`, `.bool(flag)`) or `LogValue(x)`. `LogValue(duration)` turns a
`Duration` into milliseconds.
If your app has its own `LogLevel` type, refer to Lyrelog's as `Lyrelog.Level`.
## Loggers for each area [#loggers-for-each-area]
A logger stamps its `category` on every event, like OSLog's `Logger(category:)`. It has every
level except `trace`, plus `log` and `captureError`.
```swift
let sync = Lyrelog.Logger(category: "sync")
sync.warning("sync_conflict", attrs: ["records": 2])
```
## Users [#users]
```swift
Lyrelog.setUser(playerID) // attached to every following event
Lyrelog.setUser(nil) // on sign-out
```
`Lyrelog.sessionID` gives the current session id, for example to show in a support screen.
The user id isn't saved between launches: call `setUser` again on each launch, once you know who
the person is.
## Screens [#screens]
Say where the person is. Lyrelog logs `screen_viewed` (area `navigation`) with the screen before
and the seconds spent on it, and tags every following event with a `screen` attribute.
```swift
Lyrelog.screen("Settings") // anywhere
SettingsView().lyrelogScreen("Settings") // or in SwiftUI, on appear
```
The event carries `screen`, `previous_screen` and `seconds_on_previous`. Calling `screen` again
with the same name logs nothing. Both forms take extra `attrs` for the `screen_viewed` event.
Turn the tagging off with `attachScreen: false`.
## Network requests [#network-requests]
Requests become `http_request` and `http_request_failed` events in the `network` area, with the
method, the host, a path whose ids are folded to `:id`, the status, the duration and the size.
Never the query string, the headers or the body.
```swift
let (data, response) = try await URLSession.shared.loggedData(for: request)
```
If your paths carry things the folding can't recognize, pass the route yourself:
`loggedData(for: request, route: "/players/:id/stats")`.
`loggedData(for:route:category:)` works on any `URLSession`. With your own client, record each request
yourself:
```swift
let clock = ContinuousClock()
let start = clock.now
let (data, response) = try await myClient.send(request)
Lyrelog.Network.record(request, response: response, error: nil, duration: clock.now - start, bytes: data.count, route: "/orders/:id")
```
`duration` is a Swift `Duration`: measure it with `ContinuousClock`, as above.
`bytes` and `category` (default `network`) are optional. 2xx and 3xx are `debug`, 4xx `warning`,
5xx and failures `error` (a canceled request is `debug`). A failure carries `error_domain` and
`error_code`.
## Errors you catch [#errors-you-catch]
```swift
do {
try await store.purchase(product)
} catch {
Lyrelog.captureError(error, category: "store")
}
```
It sends the `exception` event every SDK sends: level `error`, the attributes `error_type` and
`error_message`, and a payload with the description, the `NSError` domain and code, and the
underlying error. `attrs:` adds your own; `level:` changes the level. Each `Logger` has
`captureError` too.
## Crashes and hangs [#crashes-and-hangs]
Crashes and hangs come from MetricKit (iOS, macOS, visionOS), on by default
(`captureDiagnostics`). iOS hands them over on the next launch, so each one becomes an event at
the time it happened, without a session, in the `diagnostics` area:
| Event | Level | What it carries |
|---|---|---|
| `app_crashed` | critical | Exception, signal, termination reason, the version and device it happened on, the top frame of your app, and up to 60 frames in the payload |
| `app_hung` | error | How long it hung |
| `cpu_overuse` | warning | |
| `disk_write_overuse` | warning | |
| `slow_launch` | warning | |
A report delivered twice is stored once. Frames are offsets into each binary, not symbols:
symbolicate them with the dSYM when you need names. Each frame reads `MyApp +0x1a2b3c`: the
binary and the offset into its code, and the payload's `binary_images` gives each binary's UUID. With the
dSYM of the build that crashed (Xcode's Organizer, or your archive), `atos` turns an offset into
the function, file and line. Pass the binary's usual load address, `0x100000000` for an app on
arm64, and that address plus the offset:
```bash
atos -arch arm64 \
-o MyApp.app.dSYM/Contents/Resources/DWARF/MyApp \
-l 0x100000000 \
0x1001a2b3c
```
Check first that the dSYM's UUID (`dwarfdump --uuid MyApp.app.dSYM`) matches the one in
`binary_images`.
## Environments and platform [#environments-and-platform]
When it starts, the SDK picks the environment:
- `development` for a Debug build, any build on the simulator, or a build with an embedded
provisioning profile (development, ad hoc and enterprise signing);
- `testflight` for a build with a sandbox App Store receipt and no profile;
- `production` otherwise.
Then it asks StoreKit in the background (`AppTransaction.shared.environment`), without a prompt,
and events logged after it answers carry that answer: `xcode` is `development`, `sandbox` is
`testflight`, `production` is `production`. That's how a Mac app from TestFlight is told apart.
Offline or signed out, the first answer stays, and a Mac app counts as `production` until
StoreKit answers.
Your own runs from Xcode send `development`, while the dashboard opens on `production`: pick
**development** in the top bar to see them.
The platform is the OS (`ios`, `macos`, `tvos`, `visionos`; `apple` on watchOS). Override either
in the configuration:
```swift
Configuration(apiKey: key,
environment: isInternalTester ? "internal" : nil, // nil = detected
platform: nil)
```
`Lyrelog.detectedEnvironment` is the answer at start; `await Lyrelog.detectEnvironment()` waits
for StoreKit too (up to 10 seconds). Any name works: lowercase letters, digits, `-` and `_`, up
to 32. Other text is turned into a valid name (`Staging EU` becomes `staging-eu`).
## Platforms [#platforms]
| | iOS, iPadOS, visionOS | tvOS | macOS | watchOS |
|---|---|---|---|---|
| `platform` | `ios`, `visionos` | `tvos` | `macos` | `apple` |
| Sends when the app goes to the background | Yes | Yes | No | No |
| Crashes and hangs (MetricKit) | Yes | No | Yes | No |
Without a background send, events are sent on the timer while the app runs, and what's left
goes out on the next launch, since the queue is on disk. On watchOS, `os_name` is `unknown`.
## Consent [#consent]
```swift
Lyrelog.start(Configuration(apiKey: key, consent: .pending))
// later, when the person chooses:
Lyrelog.setConsent(.granted) // sends, including what was kept while pending
Lyrelog.setConsent(.denied) // deletes everything and stops recording
```
`.pending` keeps events on the device without sending them. Starting with `consent: .denied`
deletes anything still queued from an earlier launch and the install id, and records nothing.
Consent isn't saved between launches: store the person's choice yourself and pass it to
`start` each time.
## A complete app [#a-complete-app]
Start with the stored consent, set the person when they sign in and tag screens:
```swift
import Lyrelog
import SwiftUI
@main
struct MyApp: App {
init() {
let consent: Lyrelog.Consent = switch UserDefaults.standard.string(forKey: "diagnostics") {
case "granted": .granted
case "denied": .denied
default: .pending
}
Lyrelog.start(Configuration(apiKey: "lyr_ing_...", consent: consent))
}
var body: some Scene {
WindowGroup { RootView() }
}
}
struct RootView: View {
@State private var account: Account?
var body: some View {
Group {
if let account {
HomeView(account: account).lyrelogScreen("Home")
} else {
SignInView { signedIn in
account = signedIn
Lyrelog.setUser(signedIn.id)
Lyrelog.info("signed_in", category: "auth")
}
.lyrelogScreen("Sign in")
}
}
}
}
func choose(_ allowed: Bool) {
UserDefaults.standard.set(allowed ? "granted" : "denied", forKey: "diagnostics")
Lyrelog.setConsent(allowed ? .granted : .denied)
}
```
## Flush and stop [#flush-and-stop]
On iOS, tvOS and visionOS, going to the background already flushes (with a background task),
so you rarely need to.
```swift
await Lyrelog.flush() // write everything to disk and try to send now
await Lyrelog.stop() // send what's queued (up to 2 seconds), then stop
```
Without `await` (from synchronous code), `Lyrelog.stop()` stops at once and sends nothing:
events still in memory are lost, and what was queued on disk goes out after the next `start`.
`flush` respects a `Retry-After` the server asked for: it doesn't send sooner.
On macOS, send what's left when the app quits by holding the quit for a moment:
```swift
final class AppDelegate: NSObject, NSApplicationDelegate {
func applicationShouldTerminate(_ sender: NSApplication) -> NSApplication.TerminateReply {
Task {
await Lyrelog.stop() // sends what's queued, up to 2 seconds
sender.reply(toApplicationShouldTerminate: true)
}
return .terminateLater
}
}
// In your App: @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
```
## In development and tests [#in-development-and-tests]
Don't call `Lyrelog.start` in unit tests or previews: anything logged before `start` is
ignored, so the rest of your code runs unchanged.
```swift
if ProcessInfo.processInfo.environment["XCTestConfigurationFilePath"] == nil {
Lyrelog.start(Configuration(apiKey: "lyr_ing_..."))
}
```
`mirrorToOSLog: true` also prints every event to Xcode's console while you work.
## Verified events [#verified-events]
A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).
On a real iPhone, iPad or Apple Watch, the SDK proves with Apple's App Attest that events come
from your genuine app, and Lyrelog stores them as verified (`verified_by` is `app_attest`). The
option `appAttest` is `true` by default; it needs:
- The **App Attest** capability on the app target (Signing & Capabilities), the entitlement
`com.apple.developer.devicecheck.appattest-environment`. Set it to `production` for App Store
and TestFlight builds; without it Apple uses the development environment.
- Your **App ID**, the Team ID, a dot and the bundle id (`ABCDE12345.com.example.app`), in the
project's settings, section
[Verified events from your Apple apps](/projects/settings#verified-events-from-your-apple-apps).
Until it's set, the SDK stops trying for that launch.
Sending never waits for it: batches go without a token until the device has one, so the first
events of a fresh install arrive unverified, as do events sent whenever anything fails. Only the
key's id is kept, in the Keychain, and a denial of consent deletes it. Turn it off with
`appAttest: false`.
To check, open the [explorer](/dashboard/explorer): in **Filter**, pick **Verified by** and
**App Attest** (the other values are **Server key** and **Not verified**). An opened event says it under
**Context**, in its **Sender** line: **Verified, App Attest**, or **Not verified, public key**.
Macs (Apple doesn't offer App Attest there), the simulator, app extensions (except on watchOS)
and devices without App Attest always send unverified events, even with everything set up:
the ingest key is public, so anyone holding it could have sent the same. A verified event
proves which app sent it, not that what it says is true.
See [Verified events](/concepts/verification) for who verifies what and the daily share.
## Configuration [#configuration]
| Option | Default | Meaning |
|---|---|---|
| `endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is stripped. `https` only, `http` only for localhost |
| `apiKey` | required | The project's ingest key |
| `consent` | `.granted` | `.pending`, `.granted` or `.denied` |
| `minimumLevel` | `.debug` | Events below it never reach the disk |
| `mirrorToOSLog` | `false` | Also print every event to the unified log (Console, Xcode) |
| `uploadInterval` | 15 s | How often the uploader wakes in the foreground |
| `pauseUploadsInLowPowerMode` | `true` | Periodic uploads pause; going to the background still sends |
| `maxBatchBytes` | 512 KiB | A batch closes at whichever limit comes first (kept between 64 KiB and 4 MiB) |
| `maxBatchEvents` | 500 | At most 2,000 |
| `maxDiskBytes` | 20 MB | Cap on the queue on disk, oldest first |
| `maxEventAge` | 7 days | Older queued events are dropped |
| `sessionTimeout` | 30 min | Idle time that starts a new session |
| `storageDirectory` | Library/Caches/lyrelog | Where the queue lives |
| `captureDiagnostics` | `true` | MetricKit crashes, hangs and overuse reports |
| `attachScreen` | `true` | Tag events with the current screen |
| `environment` | detected | Any valid name, or `nil` |
| `platform` | the OS | Any valid name, or `nil` |
| `appAttest` | `true` | Verify events with Apple's App Attest on supported devices |
## Delivery and limits [#delivery-and-limits]
| | |
|---|---|
| Never blocks | Logging copies the event and returns; one background writer puts it on disk. |
| Survives kills and offline | A queue in Library/Caches, capped at 20 MB and 7 days. The system may purge Caches when the device is short of space, and the waiting events go with it. |
| Batches | Up to 500 events or 512 KiB per request, gzipped. An event over 1 MiB once encoded is dropped and counted. |
| Retries | 1 s doubling to 5 min, with full jitter, honoring `Retry-After`. Any other 4xx drops the batch, a 3xx (a redirect, never followed) drops it with a warning, and a revoked key (`401`, `403`) stops sending until the next launch. A batch the server keeps failing while others go through goes to the back, then is dropped. |
| Monthly quota | When a Free organization has used its month's events, the server answers `429`. Events stay in the queue on disk and go out once the server takes them again, within the 20 MB and 7 day caps. The SDK logs one warning (unified log, subsystem `com.lyrelog.sdk`) per quota stop. |
| Drops are visible | Events lost to the caps become one `lyrelog_events_dropped` warning (area `lyrelog`) with the count. |
| Its own problems | A wrong endpoint, a refused key or rejected lines go once per launch to the unified log, subsystem `com.lyrelog.sdk`, at debug level (in Console, turn on **Include Debug Messages**). |
| Context | App id, version, build, OS, device model (`iPhone18,1`), locale, session id and install id. |
| Secrets | Values under keys whose name is or ends with `authorization`, `cookie`, `password`, `token`, `secret`, `apikey` and the rest of the [shared list](/sdks#what-every-sdk-does-for-you) become `"[redacted]"`, at any depth, before anything is cut. |
| Limits | Long strings cut on a character boundary, extra attributes counted in `lyrelog_dropped_attrs`, payloads over 64 KiB summarized as `{"lyrelog_truncated": true, "bytes": N, "preview": "..."}`. |
Change the list with `redactedKeys`: your list replaces the defaults, and `[]` turns redaction
off. To add to it:
```swift
Lyrelog.start(Configuration(
apiKey: "lyr_ing_...",
redactedKeys: Lyrelog.Configuration.defaultRedactedKeys + ["pin"]
))
```
## Privacy manifest and App Store privacy [#privacy-manifest-and-app-store-privacy]
The package ships a privacy manifest (`PrivacyInfo.xcprivacy`) that Xcode merges into your app's
privacy report: no tracking, no tracking domains, the file timestamp API with reason `C617.1`
(the queue reads its own files' sizes), and the data it collects (crash data, performance data,
other diagnostic data, a device id), not linked to the person and not used for tracking.
For the App Store privacy label, declare what your app sends through Lyrelog:
- **Diagnostics:** Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
- **Identifiers > Device ID:** the install id, a random UUID that isn't the advertising id,
isn't backed up and is deleted on a denial (App Functionality). Not linked to the person
unless you also call `setUser`.
- **Identifiers > User ID**, linked to the person: only if you call `setUser`.
- **Usage Data > Product Interaction:** if you log screens (`screen_viewed`) or taps.
- Anything else your `attrs` or `payload` carry (emails, purchases...), under its own category.
The server adds the country of the sending address; the address itself isn't stored.
# Self-hosting
> Running Lyrelog on your own server isn't offered yet.
Source: https://docs.lyrelog.com/self-hosting
Lyrelog is a hosted service for now. You can't run it on your own server yet, and there are no
instructions for it.
Your events are stored on Lyrelog's servers in Germany. Backups are kept for at most 30 days: on the
same servers, and as an encrypted copy in Backblaze's EU data center in the Netherlands that
Backblaze can't read. See the
[privacy policy](https://lyrelog.com/privacy) and the
[data processing agreement](https://lyrelog.com/dpa).
If you need to self-host, write to [hello@lyrelog.com](mailto:hello@lyrelog.com).
# No events arrive
> The usual reasons an event doesn't show up, and how to tell which one it is.
Source: https://docs.lyrelog.com/troubleshooting
Send one event with curl first (see the [Quickstart](/quickstart)). The answer tells you most
of what's wrong.
| What you see | Why | What to do |
|---|---|---|
| `200` with `"accepted":0` and a `rejected` list | Each line says why it was refused | Fix the field it names (see [the common line errors](/http-api#a-rejected-line)). Never resend rejected lines. |
| `401` `unknown or revoked key` | The key is wrong, was revoked, or isn't a Lyrelog key | Copy the key again, or make a new one on **API keys** |
| `403` `this key cannot write events` | It's a **Read events** key | Use a **Send events** key (`lyr_ing_`) |
| `415` | `Content-Type` isn't `application/x-ndjson` | Set the header |
| `429` with `plan`, `limit` and `used` | The Free month is used up | The SDKs keep the events and send them when the month turns. See [Plans and usage](/account/plans) |
| `429` with `source_limit` | One address sent its share of the day with a public key | From a server, use a server key (`lyr_srv_`). Otherwise events resume the next UTC day. See [the daily share of one address](/concepts/verification#the-daily-share-of-one-address) |
| `429` `rate limit for this project` | Over 60,000 events a minute | Wait for `Retry-After` |
| `425` with `verification_required` | The project accepts only verified events from that platform, and this batch isn't verified | The SDK keeps it and retries. Builds, simulators, emulators and devices that can't prove themselves never get through: turn the option off in [Project settings](/projects/settings) while they matter. See [Verified events](/concepts/verification#accept-only-verified-events-from-the-ios-app) |
| `503` | The server is busy or can't reach its storage for a moment | Retry the same bytes after `Retry-After` (the SDKs do) |
| A `3xx` | The endpoint is wrong | Use `https://ingest.lyrelog.com` |
| Accepted, but not in the dashboard | The dashboard shows one environment: builds you run from Xcode, the simulator, Android debug builds, `localhost` and Node without `NODE_ENV=production` send `development` | Pick **development** or **All environments** in the top bar, and **All platforms** |
| Accepted, but at the wrong time | The `ts` was older than the retention or more than a day ahead, so it was stored at its arrival time | Look at the attribute `_lyrelog_ts_clamped`, and send the current time |
| Nothing at all from a Swift app | The SDK sends nothing while consent is `.pending` or `.denied` | See [Consent](/sdks/swift#consent) |
| Nothing at all from an Android app | The SDK sends nothing while consent is `PENDING` or `DENIED`, or the endpoint isn't one it accepts | See [Consent](/sdks/android#consent) and [In development and tests](/sdks/android#in-development-and-tests) |
| Nothing at all from a React Native or Flutter app | Consent is `pending` or `denied`, the endpoint isn't one the native SDK accepts, or the app wasn't rebuilt after adding the package | See Consent for [React Native](/sdks/react-native#consent) and [Flutter](/sdks/flutter#consent), and Flutter's [In development and tests](/sdks/flutter#in-development-and-tests) |
| Nothing at all from a JVM server | The key is empty (`start` returns `false` and does nothing), or the process ended before the shutdown hook could send | See [Start](/sdks/jvm#start) and [Flush and stop](/sdks/jvm#flush-and-stop) |
| Events from your server in the wrong country | The country is the sender's address | See [Countries](/concepts/countries) |
## What the SDKs say [#what-the-sdks-say]
Each SDK reports its own problems (a wrong endpoint, a refused key, a dropped batch) without
crashing your app:
| SDK | Where to look |
|---|---|
| Swift | The unified log, subsystem `com.lyrelog.sdk`: Console.app or Xcode's console |
| Android | Logcat, tag `Lyrelog`, at debug level |
| React Native | The native SDK's log: the unified log on iOS (Xcode's console), logcat on Android, as above. A missing key or native module is one `console.warn` in development builds, in Metro |
| Flutter | The native SDK's log: the unified log on iOS (Xcode's console), logcat on Android, as above. `mirrorToConsole: true` also prints every event there |
| JavaScript | `console.warn` lines starting with `[lyrelog]` |
| Python | The `lyrelog` logger (standard `logging`) |
| Go | `Config.ErrorLog`, else the first problem once on stderr |
| JVM | Standard error, lines starting with `lyrelog: `, once per process, or `Configuration.diagnostics` |
## Still stuck? [#still-stuck]
Write to [hello@lyrelog.com](mailto:hello@lyrelog.com) with the project id (in **Project
settings**, **Details**) and the time you sent the event. Never send a key.