Skip to main content
An executing workflow emits a stream of typed events: a run starting, a task scheduled, started, completed or failed, a permit checked, a cost incurred. Every event is hash-chained into the run’s journal under .nika/traces/, the record nika trace verify checks. The same events reach you three ways: Nothing in the journal can be edited, reordered or dropped from the middle without breaking its chain. Events describe what happened; the result of a run, and its settlement, remain the source of truth for how it ended.

The event shape

Each line of nika run --json and of the journal is one event. A real task_completed line from a mock/echo run on nika 0.123.0, abridged:
The type is nika_event::Event, in the engine’s nika-event crate. nika run --json ends with a run_settled frame that is not a journal event: it carries the run’s status, cause, tasks, spend, outputs and receipt together.

Event kinds

Engine emits kinds. Most runs only produce the first two groups. A few that explain themselves in practice:
  • task_failed carries the typed error (code, message, whether it is transient), the shape on_error: routes on. A turn an agent application reports as failed on a harness seat lands here, as NIKA-1804 (transient) or NIKA-1805, never as a task_completed whose output is the error text.
  • task_cache_hit marks a task a --resume run skipped because a journaled success matched it.
  • permit_checked records a boundary decision the engine made at run time. On a harness seat, one frame per permission the application asked names its gate and the decision; a Codex command that asks to leave its sandbox (sandbox · command) is always escalate, so the run pauses for you whatever permits.exec grants. The keyless provider: system voice journals its synthesizer start on the builtin plane.
  • agent_image_observed records each image a harness seat sent: the digest and size of the received bytes, the path the application reported (never opened) and, under images: { save: }, the saved_path Nika wrote.
  • workflow_paused records a human gate holding the run; approval_decided records the answer that resumed it.
  • run_sealed is the last line of a signed journal: the signature over the chain head.
The kind set grows additively: tolerate kinds you do not know.

Read the stream

nika trace export writes <run>.otlp.jsonl beside the journal: one span per task, ready for any OTLP/HTTP collector (:4318/v1/traces) or the Jaeger UI. Model calls carry the OpenTelemetry GenAI semantic-convention attributes gen_ai.provider.name, gen_ai.request.model, gen_ai.response.id, gen_ai.response.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens and gen_ai.workflow.name, alongside Nika’s own nika.* attributes (task id and hashes, tokens, permits, the chain head). See the OTel GenAI conventions. Over HTTP, nika serve --bind streams each job’s lifecycle as server-sent events (execution.started, execution.settled…), not the per-task journal events. From TypeScript, iterate run.events(), then await run.result().

Kernel interfaces (for engine implementers)

The engine kernel also declares observability interfaces for alternative engines and future adapters: MetricsExporter, TracerProvider, BillingSink, AuditSink and SecretResolver. Engine 0.124.3 ships no production implementation of them: they exist as test doubles only. What a 0.124.3 run gives you is the journal, the --json stream, the cost fields on task events (cost_incurred, task_completed) and nika trace export.
  • ADR-113: the nine-key envelope; workflow_started carries the workflow’s name.
  • ADR-028: forward-compatibility reservations, such as StopReason::Unknown(String) in an inference response.
  • ADR-035: the telemetry seams (SpanGuard parent, SpanRef).

Traces

The hash-chained journal these events form, and how to verify it.

SDK events

The normalized vocabulary run.events() yields.

Observability

Ship the stream to your own tools.

Bindings

How values move between tasks.