Observability
Stable observation and exporter vocabulary.
Observability vocabulary appears in live observer payloads, durable observation export records, storage stream rows, and @runlane/observability exporter tick results. These values are stable public contracts for telemetry adapters, storage adapters, and operator tooling.
RunlaneObservationType
| Enum | Value | Meaning |
|---|---|---|
RunlaneObservationType.RunEvent | run_event | The observation describes a durable RunEventRecord that storage committed. |
RunlaneObservationType.RunStep | run_step | The observation describes a first-time durable step completion that storage committed. |
Both live observers and durable observation export use the same observation payload union. Payloads are sanitized by contract and do not include task payload, successful output, durable step output, failure detail, release metadata, or operator-expanded run rows by default.
RunlaneObservationSourceKind
| Enum | Value | Meaning |
|---|---|---|
RunlaneObservationSourceKind.RunEvent | run_event | The durable source is a run event id. |
RunlaneObservationSourceKind.RunStep | run_step | The durable source is a run step token. |
Observation source kind and source id link each export record back to the committed fact that produced it. The same source must produce the same observation record id across retries and exporter restarts.
RunlaneObservationExporterTickStatus
| Enum | Value | Meaning |
|---|---|---|
RunlaneObservationExporterTickStatus.Aborted | aborted | The exporter observed an aborted signal before or during the tick. |
RunlaneObservationExporterTickStatus.Exported | exported | The exporter scanned a non-empty batch, the sink accepted it, and the checkpoint advanced. |
RunlaneObservationExporterTickStatus.Failed | failed | The sink or checkpoint path failed before the checkpoint advanced; the tick includes the original error. |
RunlaneObservationExporterTickStatus.Idle | idle | The scan returned no records after the current checkpoint. |
Failed ticks are replay-safe because the checkpoint is not advanced. The long-running exporter loop retries retryable failures and untyped sink failures, but rejects non-retryable RunlaneError failures such as invalid configuration or unsupported storage capabilities. Exported ticks may still be delivered more than once externally when a sink accepts a batch but crashes before its downstream provider commits; sinks that require stronger semantics should dedupe by observation record id.
Consumer IDs And Cursors
Observation exporter consumers are ordinary Runlane id values: non-empty strings that must not contain :. Use one consumer id per independent sink, such as production_otel or production_console.
Observation cursors are opaque checkpoint values owned by storage. Pass the whole returned cursor back to the same storage adapter; do not parse stream positions or assume one backend's cursor encoding applies to another.