Sinks

Sinks route events from the Kratex runtime to external destinations. Add them to telemetry.sinks in your policy file. Each entry is a JSON object with a kind and per-kind options.

For how events flow through the pipeline before reaching sinks, see Telemetry overview.

`jsonl-file`

Appends one JSON envelope per line to a file. Synchronous: no queue, no retry.

{
  "telemetry": {
    "sinks": [
      { "kind": "jsonl-file", "path": "kratex-events.jsonl" }
    ]
  }
}

Option	Required	Description
`path`	yes	Path to the output file. Relative paths are resolved against CWD. `~/` is expanded to the home directory. Parent directories are created automatically if they do not exist.

Each line in the output file is a complete JSON envelope. To read events as they arrive:

tail -f kratex-events.jsonl | jq .

Because writes are synchronous, events are on disk before the guarded process exits.

`https-webhook`

POSTs batches of envelopes to an HTTPS endpoint. Disk-backed queue with cross-run resumption and automatic retry.

{
  "telemetry": {
    "sinks": [
      {
        "kind": "https-webhook",
        "url": "https://ingest.example.com/kratex",
        "headers": {
          "authorization": { "env": "WEBHOOK_TOKEN" }
        }
      }
    ]
  }
}

Option	Required	Default	Description
`url`	yes	—	Endpoint URL. Must be `https://`; plaintext `http://` is permitted only for loopback hosts (`localhost`, `127.0.0.1`, `[::1]`).
`headers`	no	—	Additional request headers. Values can be a literal string or `{ "env": "VAR_NAME" }`: the env form reads the value from the named environment variable at runtime.
`batchSize`	no	`50`	Maximum events per POST.
`flushIntervalMs`	no	`30000`	How often to flush the queue to the endpoint (milliseconds). Also triggered on process exit and within 500 ms of each enqueue.

Auth via environment variable

Header values accept two forms. Literal header value:

{
  "kind": "https-webhook",
  "url": "https://ingest.example.com/kratex",
  "headers": {
    "authorization": "Bearer eyJ..."
  }
}

Environment-variable reference:

{
  "kind": "https-webhook",
  "url": "https://ingest.example.com/kratex",
  "headers": {
    "authorization": { "env": "KRATEX_WEBHOOK_TOKEN" }
  }
}

Use the env form for secrets: the token stays out of the policy file.

If an env-form header references a variable that is unset or empty, the sink becomes a no-op and emits one warning to stderr: kratex: telemetry sink "https-webhook" missing env var "VAR_NAME"; skipping events.

Request format

Each POST body is:

{ "events": [ ...envelopes ] }

With Content-Type: application/json. Your endpoint should respond with any 2xx status to acknowledge receipt.

Queue behavior

Events are held in a disk-backed queue (scratchDir/webhook-<slug>.ndjson) and flushed in batches. The queue survives process exit: undelivered events are retried on the next Kratex run that uses the same webhook URL.

Queue limits:

Cap	Default
Max events in queue	500
Max total queue size	1 MiB
Max size per event	16 KiB

When any cap is exceeded, the oldest events are dropped first. Blocked and would-block policy events are exempt from these drops: other events go first, and the exempt events are removed only if the queue still exceeds the size cap once nothing else remains. Events larger than 16 KiB are dropped on enqueue with a stderr warning.