Observability

The DefenseClaw gateway is observable by design. Every decision — admission, guardrail verdict, judge call, scanner finding, HITL approval — is structured, correlated by trace_id/span_id, and emitted on three independent rails:

1audit:2  sqlite: enabled3  jsonl: enabled4exporters:5  otlp: configured_only6  splunk: configured_only7  webhooks: configured_only21audit:2  sqlite: enabled3  jsonl: enabled4exporters:5  otlp: configured_only6  splunk: configured_only7  webhooks: configured_only2

What you just saw

The same synthetic Cursor enforcement decision used on the homepage kept its trace, span, session, connector, decision, rule, and severity dimensions across local evidence and configured export rails. The example does not imply delivery to an OTLP, Splunk, or webhook destination that an operator has not configured.

You can use any combination of those — they're independent sinks, not exclusive backends. Most teams start with one of the bundled local stacks while they're building policy, then add their production SIEM as a second sink without rewriting anything.

The two bundled stacks

What lands in observability

Every event has the same envelope so you can correlate across rails:

{
  "ts": "2026-05-08T12:00:01.234Z",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "connector": "codex",
  "agent": "claudecode",
  "session_id": "...",
  "kind": "guardrail.verdict",
  "decision": "deny",
  "rule": "secrets/aws_access_key",
  "severity": "high",
  "actor": { "operator": "vineeth", "host": "..." },
  "payload": { "matched": "AKIA****", "tool": "fs.write" }
}

The connector field is the multi-connector dimension: it names which hook connector (codex, claudecode, antigravity, …) the event came from. One gateway can serve several connectors at once, so every rail carries it — see Filter by connector below.

The kind field is your top-level taxonomy:

You don't pick the schema in setup — you pick the destinations. Process-wide traces, metrics, and logs use named otel.destinations[]; audit-only forwarding uses audit_sinks[]. Both live in ~/.defenseclaw/config.yaml, and the bundled commands maintain them without storing credential values there.

Manage destinations safely

Destination names are identities: a new name adds a route, while an existing name updates only that route. Inspect and preview before writing:

defenseclaw setup observability list
defenseclaw setup observability list --json
defenseclaw setup observability add otlp --name production-tempo \
  --endpoint collector.example.com:4317 --signals traces --dry-run

The list distinguishes otel from audit_sinks and shows kind, enabled state, signals, preset, and endpoint. The TUI Overview's full-width Observability Destinations · Runtime panel shows the runtime-loaded version of the same inventory, including process/global/connector scope, explicit connector suppression, and Galileo schema eligibility plus acknowledged, rejected, and failed delivery. It never shows headers or credential values. Open 0 Setup → Observability / Galileo to add, update, enable, disable, test, or remove destinations.

Audit contracts

gateway.jsonl is still the live structured runtime log. audit_events is the SQLite audit store used by the TUI, exports, and audit sinks. The details column is intentionally backward-compatible text; new machine-readable audit payloads live in structured_json and export as structured.

Connector hook audit rows use schemas/hook-audit-envelope.json (schema: "defenseclaw.hook.v1"). During migration, the same hook envelope is also embedded in details_json= inside details so existing Splunk SPL and grep workflows keep working. New consumers should read structured.

Filter by connector

When one gateway enforces guardrail policy for several hook connectors at once (see Multi-connector), every rail carries a connector dimension so you can slice telemetry per connector:

The OTel resource attribute defenseclaw.claw.mode reports multi when more than one connector is active, so you can also tell a fan-out gateway apart from a single-connector one. Grafana's Connectors (Overview) and Connector Detail boards are built on the connector metric label, and the Guardrail Evaluations board is connector-filterable. See Local observability stack and Splunk.

Pick a starting point

defenseclaw setup local-observability up

defenseclaw setup splunk --enterprise \
  --hec-endpoint https://splunk.example.com:8088 \
  --hec-token "$DEFENSECLAW_SPLUNK_HEC_TOKEN"

defenseclaw setup local-observability up
defenseclaw setup splunk --enterprise --hec-endpoint ... --hec-token ...

Common questions