Observability

Overview

nikcli ships a small observability layer that wires the Effect runtime to OpenTelemetry and publishes a stream of captured spans on the internal bus. The layer is merged into every Effect runtime base (packages/nikcli/src/effect/runtime.ts) so the same spans power the live TUI panel, the OTLP export, and the on-disk log file.

There is no separate nikcli telemetry command. The whole subsystem is configured by environment variables and turned on or off from the TUI.

Two modes

Both modes can run at the same time. Disabling both fully deactivates the layer (no spans are even captured).

OTLP export

OTLP export uses the Effect OtlpTracer and OtlpLogger modules. The HTTP client is the standard FetchHttpClient from effect/unstable/http.

Environment variables

Headers

The header parser is permissive: a header is split on the first = only, so values may contain =. Keys and values are not URL-decoded automatically; the collector's OTEL_EXPORTER_OTLP_HEADERS semantics match the OpenTelemetry spec.

# Export to a local Jaeger collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 nikcli run "summarize this repo"

# Export to a hosted backend with auth
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.grafana.net \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20xxx" \
nikcli serve --port 4096

# Disable the live panel but keep OTLP export
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
NIKCLI_DISABLE_OTEL_LIVE=1 \
nikcli serve --port 4096

Live telemetry panel

The live panel is on by default. Each completed span is published on the telemetry.record bus event with the payload defined in packages/nikcli/src/observability/telemetry-bus.ts:

export const TelemetryRecord = BusEvent.define(
  "telemetry.record",
  z.object({
    id: z.string(),
    traceId: z.string(),
    parentId: z.string().optional(),
    name: z.string(),
    kind: z.string(),
    startTime: z.number(),
    durationMs: z.number(),
    statusCode: z.number().optional(),
    statusMessage: z.string().optional(),
    attributes: z.record(z.string(), z.string()).optional(),
  }),
)

The TUI subscribes to this event in packages/tui/src/component/dialog-telemetry-live.tsx and renders a scrolling, searchable list of spans with filter by name, kind, and status.

Configuration

All configuration is read from environment variables in @nikcli-ai/util/flag and consumed by packages/nikcli/src/observability/otlp.ts. There is no nikcli.json field for telemetry — the values are deliberately env-only so container images can be reconfigured without rebuilding.

Resource attributes

Every span is decorated with a resource block. The base attributes are:

Disabling the live panel

Set NIKCLI_DISABLE_OTEL_LIVE=1 to opt out of the in-process span capture. This is useful when you only want the OTLP export and want to skip the bus traffic.

TUI surface

The TUI exposes two dialogs that consume the same span stream:

The dialogs are registered in packages/tui/src/component/dialog-command.tsx and opened from the command palette (Ctrl+P) or by their keybind.

Effect integration

The observability layer is merged into the Effect runtime base in packages/nikcli/src/effect/runtime.ts. Application code that needs to emit a span can use the standard Effect combinators:

// Any service that uses the Effect runtime automatically gets an OTLP-capable tracer.
const program = Effect.gen(function* () {
  yield* Effect.logInfo("doing work").pipe(Effect.withSpan("session.run"))
  return yield* someOperation
})

The same span is published on the bus (so the TUI sees it) and exported over OTLP (when an endpoint is set). No extra wiring is needed per call site.

Source anchors