Observability

Rensei ships three complementary observability layers: Sentry for error and exception capture, OpenTelemetry (OTel) for distributed tracing of agent verb execution, and SIEM export for forwarding audit events to your security information platform. All three are opt-in via environment variables and operate independently.

Sentry error captureCopy Anchor Link

Sentry is instrumented at all three Next.js execution boundaries: server, client, and edge. Configuration lives in sentry.server.config.ts, sentry.client.config.ts, and sentry.edge.config.ts.

SetupCopy Anchor Link

Sentry integration is configured by the platform operator at the deployment level. Deployment-level Sentry setup (DSN, project credentials) is covered in the operator docs. Errors are enriched with user context (org ID and user ID) to enable per-tenant issue filtering.

What Sentry capturesCopy Anchor Link

• Unhandled exceptions in API route handlers
• React component render errors (via Error Boundary integration)
• Edge runtime errors (middleware, edge API routes)
• Manual Sentry.captureException() calls for known error paths (e.g., webhook signature failures, policy evaluation errors)

OpenTelemetry tracingCopy Anchor Link

The OTel exporter subscribes to the Layer-6 verb bus and emits one span per agent tool invocation. This means every pre-verb / post-verb pair produces a span - no manual tracer.startSpan() calls are scattered through the codebase.

Enabling OTel tracesCopy Anchor Link

OTel tracing is activated by the platform operator via deployment-level environment variables. The exporter sends OTLP HTTP spans to any OTLP-compatible endpoint (LangSmith, Langfuse, Arize, Honeycomb, Grafana Cloud, etc.). Deployment-level OTel configuration is covered in the operator docs.

Span attributesCopy Anchor Link

Every verb span includes:

Session eventsCopy Anchor Link

In addition to verb spans, the exporter can emit one span per SessionEvent (session start, activity, completion). The projectSessionEvent projector maps session events to OtelTraceSpan format.

Exporter failure isolationCopy Anchor Link

The OTel subscriber runs inside the verb bus's subscriber crash-isolation wrapper. A thrown or rejected span export does not block other subscribers (audit, cost, eval) and is logged at warn level.

SIEM exportCopy Anchor Link

After a current-path audit append succeeds, fanOutToSIEM starts a non-blocking delivery attempt for each configured destination that matches the event filter. A destination failure is logged and does not roll back the audit entry. This is not a guarantee that every destination received every entry, and the audit trail itself does not prove that every security-relevant action was captured.

Supported formatsCopy Anchor Link

Configuring a SIEM destinationCopy Anchor Link

SIEM destinations are managed per workspace via the API:

# Add a generic JSON webhook destination
curl -X POST https://app.rensei.ai/api/audit/siem/destinations \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "url": "https://siem.example.com/events",
    "format": "json",
    "apiKey": "<bearer-token>",
    "name": "Production SIEM",
    "filter": ["agent.spawned", "agent.completed", "approval.gate_created"]
  }'

The filter array is optional. When omitted, all audit event types are forwarded. When present, only matching eventType values are delivered.

When apiKey is present, the sender uses Authorization: Bearer <apiKey>. Vendor-specific authorization schemes, including direct Splunk HEC Authorization: Splunk ..., are not implemented by this generic sender.

Event types forwarded to SIEMCopy Anchor Link

The current audit writer supports the following representative event types; this list is not a capture-completeness claim:

agent.spawned          agent.completed         agent.failed
user.login             user.logout             user.invited
user.deprovisioned     org.member_role_changed
approval.gate_created  approval.decision_submitted  approval.gate_resolved
policy.created         policy.evaluated
audit.chain_break_detected  audit.key_rotated  audit.anchored
sso.connection_created      scim.user_provisioned
m2m.client_created          m2m.token_issued
credential.rotated          workflow.deployed

See Audit Trail for the event taxonomy, explicit verifier, and proof limits.

SIEM destination healthCopy Anchor Link

Test delivery parameters before saving a destination:

curl -X POST https://app.rensei.ai/api/audit/siem/test \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://siem.example.com/events",
    "format": "json",
    "apiKey": "<bearer-token>"
  }'
# Returns: { "ok": true } or { "ok": false, "error": "..." }

Destinations are stored in Redis under workspace:{id}:siem:destinations. Removing the destination stops further delivery immediately.

CLI observability commandsCopy Anchor Link

# Tail live audit events
rensei observability events tail --org acme-corp

# Query historical events by kind
rensei observability events query \
  --org acme-corp \
  --filter kind=agent.spawned \
  --since 2026-06-01T00:00:00Z \
  --until 2026-06-02T00:00:00Z \
  --ndjson

Failure signature registryCopy Anchor Link

The failure signature registry records observed remedies, constraints, and diagnostics. Its API uses org-scoped session or user-token authentication.

Kinds are remedy, constraint, and diagnostic. Read filters accept the observed, assisted, and auto tiers, but the create endpoint cannot promote a record to assisted or auto, or create a shared system record. Invalid tier, matcher, or provenance input is refused with 422; a duplicate key within the same scope returns 409. Creating an observed record does not authorize automatic remediation.

Related pagesCopy Anchor Link

• Audit Trail - hash-chain integrity, proof limits, retention, and optional anchoring
• Cedar Policies - policy evaluation events that appear in the audit trail
• Sessions Inspector - per-session 7-tab debug view including OTel spans