# 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.