Observability

rensei observability surfaces the Layer 6 provider lifecycle hook events emitted by the local daemon into the .rensei/audit/<date>.ndjson log files. Use it to watch events in real time with tail, or replay and filter historical events with query - useful for diagnosing credential delivery failures, provider lifecycle anomalies, and session dispatch issues.

rensei observability reads the local daemon event log. For platform-side operational telemetry (Sentry, OTel, SIEM), see Platform admin - observability. For the audit hash-chain (per-session attestations), see Audit.

Log file location

The daemon writes Layer 6 hook events to:

.rensei/audit/<YYYY-MM-DD>.ndjson

Each line is a newline-delimited JSON object (NDJSON). The file rolls over at midnight local time. observability events commands default to today's log unless --log <path> is provided.

Commands

`observability events tail`

Stream events from the log file in real time. Output updates as new events are written by the daemon.

rensei observability events tail \
  [--filter "key=value ..."] \
  [--scope project|org|tenant] \
  [--log <path>] \
  [--ndjson]

Flag	Description
`--filter "key=value ..."`	Space-separated `key=value` predicates. Events must match ALL predicates.
`--scope project\|org\|tenant`	Filter events to a specific scope level.
`--log <path>`	Path to an NDJSON log file. Defaults to `.rensei/audit/<today>.ndjson`.
`--ndjson`	Emit raw NDJSON lines instead of the pretty-printed table. Useful for piping to `jq`.

# Stream all events from the current daemon log
rensei observability events tail

# Stream only credential-related events
rensei observability events tail --filter "category=credential"

# Stream errors for a specific session
rensei observability events tail --filter "sessionId=ses_abc123 level=error"

# Pipe raw NDJSON to jq for custom filtering
rensei observability events tail --ndjson | jq 'select(.category == "credential")'

Example output (pretty table):

TIME         LEVEL   CATEGORY     SESSION                  MESSAGE
14:02:01.123 info    credential   ses_abc123               snapshot delivered (14 creds)
14:02:01.890 info    dispatch     ses_abc123               agent spawned pid=48291
14:02:04.201 warn    credential   ses_abc123               rotate-stream reconnect attempt 1
14:02:05.312 info    credential   ses_abc123               rotate-stream connected
14:02:18.004 info    lifecycle    ses_abc123               session terminal: success

`observability events query`

Query historical events from the log with optional time bounds and filters.

rensei observability events query \
  [--filter "key=value ..."] \
  [--since <RFC3339>] \
  [--until <RFC3339>] \
  [--log <path>] \
  [--ndjson]

Flag	Description
`--filter "key=value ..."`	Same predicate syntax as `tail`.
`--since <RFC3339>`	Include only events at or after this timestamp.
`--until <RFC3339>`	Include only events at or before this timestamp.
`--log <path>`	Path to an NDJSON log file.
`--ndjson`	Emit raw NDJSON.

# Query all events from the last hour
rensei observability events query \
  --since "$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)"

# Query credential errors for a specific session
rensei observability events query \
  --filter "sessionId=ses_abc123 level=error category=credential"

# Query a specific date's log
rensei observability events query \
  --log .rensei/audit/2026-05-31.ndjson \
  --filter "level=error" \
  --ndjson | jq '{time: .timestamp, msg: .message}'

# Find all sessions that hit the snapshot-failed fallback
rensei observability events query \
  --filter "key=RENSEI_CREDENTIAL_SNAPSHOT_FAILED"

Event schema

Each NDJSON line has the following structure:

{
  "timestamp": "2026-06-02T14:02:01.123Z",
  "level": "info",
  "category": "credential",
  "scope": "project",
  "sessionId": "ses_abc123",
  "projectId": "proj_xyz",
  "orgId": "org_acme",
  "message": "snapshot delivered (14 creds)",
  "data": {
    "credentialCount": 14,
    "durationMs": 42
  }
}

Prop

Type

Event categories

Category	Description
`credential`	Credential snapshot delivery, rotate-stream events, and snapshot failures
`dispatch`	Agent spawn, PID assignment, and pre-spawn hooks
`lifecycle`	Session state transitions (queued → running → terminal)
`capacity`	Pool slot acquired/released, eviction events
`provider`	Provider capability checks and initialization
`error`	Unhandled errors surfaced by Layer 6 hooks

Common diagnostic patterns

Credential snapshot failed

If an agent session starts but tools cannot authenticate to external services, look for the RENSEI_CREDENTIAL_SNAPSHOT_FAILED signal:

rensei observability events query \
  --filter "category=credential level=warn"

If you see snapshot failed, agent using socket fallback, the credential socket is still active but the pre-spawn snapshot did not complete. The agent will request credentials on demand via the socket instead. Check ~/Library/Logs/rensei/daemon-error.log for the root cause.

Rotate-stream disconnects

Repeat rotate-stream reconnect attempt events indicate the daemon is having trouble maintaining the SSE credential rotation stream to the platform. This is often a network issue (proxy, firewall) or an expired daemon JWT.

rensei observability events tail --filter "category=credential message=rotate-stream"

Check rensei host status and rensei host doctor for JWT health.

Slow dispatch

High durationMs values in dispatch events indicate slow pre-spawn hooks - usually workarea preparation or a large credential snapshot. Use rensei host capacity status --pool to confirm the pool is not oversubscribed.

Host - credential socket - unix-socket credential protocol and the blocklist of env vars agents never receive
Audit - attestations - per-session VCS attestations and the Merkle audit chain
Platform admin - observability - Sentry/OTel/SIEM integration for platform-side telemetry
Host daemon - logs - rensei host logs for the daemon stdout stream

On this page