Tracing and Auditing

Nexus separates three related data classes:

1. Audit events — always-on accountability records for security, access, configuration, routing, lifecycle, and policy decisions.
2. Tenant analytics metadata — always-on operational rows for request/session visibility, cost, latency, status, routing, and safe tool summaries.
3. Full trace payloads — opt-in debug artifacts containing request bodies, response bodies, tool arguments, tool results, and replayable context.

Every request is accountable; full payload traces are opt-in.

When full tracing is disabled, Nexus still records request/session metadata and emits audit events.

The request row keeps identifiers, timestamps, model/provider, status, latency, token and cost fields, attempt trail, trace flags, body byte counts, body hashes, and safe tool summaries.

Nexus does not persist request bodies, response bodies, full tool arguments, full tool results, or replayable conversation context.

Full tracing is enabled when any of these sources is enabled:

• nexus-enable-tracing: 1 on the request.
• API-key trace logging setting.
• Project trace logging setting.
• Organization trace logging setting.

When enabled, Nexus can persist full request/response bodies and tool-call trace artifacts and expose them through authenticated query APIs.

Nexus-native agentic trace storage is a shipped pipeline: the trace-ingest service accepts OTLP/HTTP trace exports under project-scoped ingest keys, ingest materializes normalized spans/events/artifact refs into ClickHouse, and query plus the console trace inspector expose tenant-scoped reads.

The contract uses OpenTelemetry trace identifiers and OpenInference semantic attributes, but Nexus tenancy and authorization come from authenticated Nexus context, not from submitted span attributes alone.

The trace contract distinguishes:

• Trace span metadata — operation identity, timing, status, hierarchy, model/provider, token/cost summaries, agent/tool names, request joins, and filtered attributes.
• Trace events — point-in-time lifecycle or log events attached to a trace or span.
• Trace artifacts — large or sensitive payloads such as span inputs, span outputs, tool arguments, tool results, retrieved document content, images, audio, and raw provider payloads.

State	Meaning
summary_only	Nexus keeps safe metadata or a short summary, but no full payload bytes.
full	Nexus stores the full payload artifact because full tracing is enabled and policy allows capture.
omitted	Nexus intentionally does not store the payload, but can retain byte counts and hashes when available.
redacted	Nexus stores only a policy-redacted representation or redaction metadata.

OpenInference attributes such as session.id, user.id, llm.model_name, tool.name, and agent.name can be preserved for interoperability and UI rendering.

Nexus-owned attributes such as nexus.org_id, nexus.project_id, nexus.request_id, nexus.classification, nexus.trace_source, nexus.payload_state, and nexus.artifact_ref carry Nexus-specific correlation and governance information.

Incoming Nexus scope attributes are treated as hints; authenticated Nexus context remains authoritative.

Trace settings do not disable audit events.

Audit events remain the evidentiary path for accountability and tamper-evident sealing (the audit service runs in the stock Compose stack). Trace artifacts are developer debugging data with separate storage and retention concerns.