.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 ofnika 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_failedcarries the typed error (code, message, whether it is transient), the shapeon_error:routes on. A turn an agent application reports as failed on a harness seat lands here, asNIKA-1804(transient) orNIKA-1805, never as atask_completedwhose output is the error text.task_cache_hitmarks a task a--resumerun skipped because a journaled success matched it.permit_checkedrecords 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 alwaysescalate, so the run pauses for you whateverpermits.execgrants. The keylessprovider: systemvoice journals its synthesizer start on thebuiltinplane.agent_image_observedrecords each image a harness seat sent: the digest and size of the received bytes, the path the application reported (never opened) and, underimages: { save: }, thesaved_pathNika wrote.workflow_pausedrecords a human gate holding the run;approval_decidedrecords the answer that resumed it.run_sealedis the last line of a signed journal: the signature over the chain head.
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.
Related decisions
- ADR-113: the nine-key envelope;
workflow_startedcarries the workflow’s name. - ADR-028: forward-compatibility reservations, such as
StopReason::Unknown(String)in an inference response. - ADR-035: the telemetry seams (
SpanGuardparent,SpanRef).
Read next
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.