Skip to main content
A project is the access boundary for telemetry. Every native telemetry envelope includes one project_id, and every read command can filter by project. Use projects for the smallest unit that should have its own access and retention boundary. For most teams, that is one app, service, or product area.

​
Project, service, environment

1

Create or choose a project

Pick one project for the product area you want to observe. Keep the project stable so historical telemetry remains easy to query.
CLI v0.1.30 or newer creates the backend-owned project and stores its one-time ingest key in a new owner-only file without printing the key or its path. projects setup records shared setup state for an existing project. logbrew setup --create-project remains discovery help only and does not create a project.
2

Set service names in SDKs

Use names agents already understand from your repo and deploy system, such as api, worker, web, ios, or checkout-api.
3

Use standard environments

Prefer production, staging, preview, and local. Avoid custom names unless your deploy process already uses them everywhere.
4

Filter reads by project when needed

​
Diagnose project setup

Run logbrew doctor --project <project_id> --json before inferring setup state from logs. The CLI reads the canonical GET /api/projects/{project_id}/doctor contract with stored account authentication. The endpoint accepts a project UUID in the path and has no query parameters or request body.
1

Read the canonical project diagnosis

Keep the project UUID in protected local configuration and let the CLI use its stored account authentication.
Direct API clients can call the same path with account bearer authentication. Never use a project ingest key for this read.A successful 200 response has exactly these keys: project_id, state, setup_status, setup_acknowledged, has_active_ingest_key, first_telemetry_seen_at, last_seen_at, last_signal, next, and next_action.first_telemetry_seen_at and last_seen_at are RFC3339 timestamps or null. last_signal is a display-safe project signal summary or null; it is not a raw signal body.
2

Follow the returned state and action

Do not derive setup state from local files or an empty telemetry query. Use the exact state and action pair returned by the doctor response.setup_status is one of created, setup_started, sdk_seen, first_telemetry_seen, or active. setup_acknowledged is true only when the status is sdk_seen, first_telemetry_seen, or active.
3

Use a recent log only as optional visibility

GET /api/logs?project_id=<uuid>&limit=1 can check for one recent visible log after the doctor response directs you to telemetry reads. A bare [] means only that this query found no matching visible log. It does not mean the project is missing, and it does not prove the project has never received telemetry.
4

Recover without probing or exposing data

If the read still fails, create a private support ticket. Tickets are private to the submitting account and LogBrew support, but reports must omit credentials, authorization headers, hosts, raw signal bodies, customer data, project IDs, local paths, and source code. Use only the support guide’s strict diagnostic allowlist.

​
Rotate an ingest key without telemetry loss

Rotate in this order: create, deploy, verify, then revoke. Every key-management request uses account authentication. The examples use an account access bearer; an authenticated account session has the same management role. A project-scoped ingest key can send telemetry only and must not manage keys.
Never revoke the old key first. Keep it active until the replacement is deployed and a new synthetic event is visible through an authenticated read.
1

Create the replacement key

POST /api/projects/{project_id}/ingest-keys accepts a trimmed, non-empty label up to 120 characters, a kind of exactly cli, sdk, browser, or server, and an optional future RFC3339 expires_at timestamp.Capture the response without printing it. This example requires jq and keeps both account and project credentials in shell variables rather than command history:
A successful 200 response contains id, label, kind, token, created_at, expires_at, next, and next_action. The token starts with lbw_ingest_ and is returned once.Never print the token, paste it into a ticket, commit it, or put its value in command history. An optional Idempotency-Key can make an exact create retry safe; keep that value private, do not print it, and reuse it only for the identical request.
2

Deploy the new key while the old key stays active

Write new_ingest_key directly into the existing protected deployment setting for the same project, then deploy the app normally. Do not remove or revoke the old key during this step, and do not place either value in source files, build output, or logs.
3

Verify one synthetic event and read it back

After configuring the replacement, send one placeholder-only info log with the new key:
Continue only after the ingest response accepts one log and the account- authenticated read returns ingest key rotation check. Also confirm the newly deployed app is producing telemetry before removing a key that older instances may still use.
4

List secret-free key metadata

Use account authentication to identify the old key ID and confirm the new key is active:
GET returns a bare array. Each item contains id, label, kind, token_prefix, status, created_at, expires_at, and revoked_at. Status is active, expired, or revoked. The list never contains token or token_hash.
5

Revoke only the old key

Set OLD_KEY_ID from the secret-free list, verify it is not new_key_id, then revoke it with account authentication:
DELETE is idempotent and returns the same secret-free metadata. Success reports status: "revoked" with revoked_at set, so an exact retry after an uncertain response is safe.

​
Recover safely

If rotation still fails, create a private support ticket. Tickets are private to the submitting account and LogBrew support, but reports must still omit credentials, authorization headers, hosts, raw logs, request payloads, customer data, local paths, and source code. Share only secret-free key metadata and the strict diagnostic allowlist from the support guide.