Telemetry overview

Kratex emits structured events as it runs: policy events from the guarded process and install-lifecycle events from the CLI. Every block, audit event, and allow line in your terminal comes from the CLI’s built-in reporter; sinks route events beyond the terminal, to a file or a remote endpoint.

When telemetry.sinks is omitted from your policy, no external routing occurs. Adding a sink opts into that destination.

What emits events

Two event types share the same pipeline:

Policy events. Blocked, would-block, and audited operations each produce one. Allowed operations are quieter: a matched allow rule emits nothing, and a default allow (no rule matched) emits only when the target carries a data class, the signal that an unmatched package touched something sensitive. The event carries the action, the caller chain, the target, the matched rule, and the effective severity.
Install-lifecycle events. kratex install, kratex ci, and kratex audit emit started and ended envelopes for each npm phase, correlated by runId.

Every sink receives every envelope: there is no per-sink type filter.

Sink activation

{
  "telemetry": {
    "sinks": [
      { "kind": "jsonl-file", "path": "events.jsonl" },
      { "kind": "https-webhook", "url": "https://ingest.example.com/kratex" }
    ]
  }
}

`telemetry.sinks` value	Effective behavior
omitted	No external sinks. Terminal output still works via the built-in reporter.
`[]` (empty array)	No external sinks. Explicitly suppresses any default.
explicit array	Only the sinks you list are active.

The OSS CLI implements two sinks: jsonl-file and https-webhook. The schema also accepts a third kind, kratex-cloud, which has no implementation in this build: the CLI accepts the policy, warns once on stderr, and drops that sink’s events. Any other kind fails validation at startup.

The event envelope

Every sink receives the same envelope. This is the wire format for jsonl-file (one per line) and for https-webhook (wrapped in { "events": [...] }):

{
  eventId: string;          // uuid, one per envelope
  occurredAt: string;       // ISO-8601 timestamp
  installId: string;        // persistent per-machine UUID at <configDir>/install-id; never empty (falls back to an ephemeral per-process id)
  projectId: string | null; // always present; null in the OSS CLI
  runId: string;            // correlates parent CLI and child Node events
  machine: {
    hostname: string;       // 8-char SHA-256 prefix of the hostname (no raw name, no PII)
    platform: string;       // "darwin" | "linux" | "win32"
    arch: string;           // "x64" | "arm64" | ...
    nodeVersion: string;    // e.g. "v22.14.0"
    cliVersion: string;
  };
  type: "policy" | "install-lifecycle";
  event: PolicyEvent | InstallLifecycleEvent;
}

`runId`: correlating parent and child

runId is a UUID minted by the CLI on every invocation and exported to the child Node process as KRATEX_RUN_ID. The runtime preload reads it and uses the same value, so every envelope (install-lifecycle from the parent, policy events from the child) carries the same runId. Join on runId to reconstruct a single logical kratex run or kratex install invocation across the process boundary.

Path normalization

Policy events normalize file paths inside the workspace to workspace-relative form before they leave the process. Absolute paths outside the workspace are not redacted: outside-workspace paths are the signal, and they appear verbatim in the target field.

Per-sink error isolation

The dispatcher wraps every sink.send() call so one failing sink cannot break another. Synchronous throws and rejected promises are both caught. Each (sink kind, error message) pair emits exactly one warning to stderr; repeated errors with the same message are suppressed.

Shutdown drain

On process exit, Kratex gives sinks up to 5 seconds to flush. Synchronous sinks (jsonl-file) return immediately. The queue-backed sink (https-webhook) flushes any pending batch within the budget; events still in flight at 5 seconds are left in the queue for the next run.