Product pages

Lumen

Observability control plane — structured logs, SHA-256 error groups, traces/spans, metrics, Pulse, and a query/MCP API

Lumen is Orkestia's telemetry store and triage engine. It is a separate host from the workflow API: ingest and query live at https://lumen-api.orkestia.dev. The org is off until provisioned; every write then fails with 403 / LUMEN_NOT_PROVISIONED.

Signals are JSON over HTTP (not OTLP protobuf). Grouping is async: ingest persists first, then a fingerprint processor links ERROR / WARNING / CRITICAL lines into error groups and evaluates alert rules.

This section is the contract: provision, keys, ingest schema, query API, collector, app, MCP. Start at Enable or jump to Send data / Query API.

Surfaces

Surface	URL	Auth
Provision / plan	app.orkestia.dev/governance/lumen	Org admin session
App	lumen.orkestia.dev	Same Orkestia session
Cockpit app	Orkestia Cockpit desktop, Lumen mode	The Cockpit sign-in; see Lumen in the Cockpit app
API	`https://lumen-api.orkestia.dev`	`X-Api-Key: lumk_…` (ingest/read) or `lump_…` (Pulse); query also accepts org Bearer
MCP	`https://mcp-lumen.orkestia.dev/mcp`	`Authorization: Bearer` (org token). Separate from `mcp.orkestia.dev`
Health	`GET https://lumen-api.orkestia.dev/health`	none → `{"status":"healthy"}`

Pipeline

producer  --POST /api/logs|metrics|product/ingest[--/batch]-->  Lumen API
                |  optional: Kafka topic lumen.logs (same JSON as HTTP logs)
                v
         normalize / redact / ingest-rules (drop|sample)
                v
         persist  →  201 { id, received_at }   |  200 { dropped: true }  |  429 quota
                v
         fingerprint (sync hash) + queue
                v
         processor: error groups · alert rules · lumen.alert.fired (ticket channel)
                v
         GET /api/logs · /error-groups · /traces/{id} · /metrics · MCP

Signal	Write	Read
Logs	`POST /api/logs/ingest[/batch]`	`GET /api/logs`, `/logs/stats`, `/logs/pulse`
Error groups	derived from logs (not a write API)	`GET /api/error-groups`; mutations `PATCH …/resolve\|ignore\|reopen\|assign\|severity`
Traces / spans	log fields `trace_id`/`span_id`, and/or `POST /api/traces` + `…/spans`	`GET /api/traces/{trace_id}`, `/spans/stats\|slow\|errors`
Metrics	`POST /api/metrics/ingest[/batch]`	`GET /api/metrics`, `/aggregate`, `/names`, `/dimensions`
Pulse	`POST /api/product/ingest[/batch]` with `lump_`	`GET /api/product/events`, `/stats`

Batch bodies are { "items": [ … ] } (Pulse also accepts "events"). Max 1000 items; browser Pulse keys cap at 50.

Keys

Prefix	Scope	Header	Allowed
`lumk_…`	`ingest`	`X-Api-Key`	Log + metric writes
`lumk_…`	`read`	`X-Api-Key`	GET/HEAD query only (`403 WRITE_ACCESS_REQUIRED` on mutations)
`lump_…`	`product`	`X-Api-Key` or `Authorization: Bearer`	Pulse only

The key binds the org. Do not send organization_uuid / X-Lumen-Organization-UUID on customer keys. Never put lumk_ ingest keys in a browser; Pulse browser keys can be origin- and project-locked. From a web app, send Pulse events with the Pulse SDK.

In this section

Enable

Provision, plans, rate limits, mint lumk_ / lump_.

Send data

Ingest schema, status codes, fingerprint algorithm, SDK, Kafka.

Query API

Filters, pagination, traces, metrics aggregate, rule JSON.

Collector

DaemonSet → /api/logs/ingest/batch + /api/metrics/ingest/batch.

App

UI paths mapped to the same API.

MCP

Tool inventory on mcp-lumen.orkestia.dev.

Lumen in the Cockpit app

Dashboards, observe, AI analytics, Pulse, rules and plans inside the desktop app.

Settings and bulk actions

Account, plan limits, value labels and acting on several error groups at once.

Custody

Lumen stores telemetry you sent (lines, fingerprints, spans, series, triage notes) plus what grouping derived. It does not store source or App Data rows. A secret in message / traceback / context is stored. Use structured fields, ingest drop rules, and keep credentials out of logs. See Security & compliance.

Scoped SQL on your own database

Let your app's signed-in users read rows from a Postgres database you operate, through a login bound to their workspace, with filters that can only narrow.

Explore and correlate

Logs, error groups, traces, spans, metrics, projects, infrastructure and MCP in the Cockpit app, and the links that connect them to each other and to Cockpit