Lumen
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.
Surfaces
| Surface | URL | Auth |
|---|---|---|
| Provision / plan | app.orkestia.dev/governance/lumen | Org admin session |
| App | lumen.orkestia.dev | Same Orkestia session |
| 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.
In this section
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.