Start free
Menu

Product

Start free
Docs menu

From the open engine’s docs (traza 0.28.0). View source Engine routes reach a Traza Cloud project through the gateway.

Module map

What each file in src/ is responsible for, and where to start looking for a given change.

Crate rules

Three direct dependencies: serde, serde_json, and lz4_flex (pinned to an exact version, because compressor output bytes are format bytes — argued in dependencies). HTTP, threading, hashing, protobuf decoding, SHA-256, and file I/O are all standard library or hand-written. The crate is #![forbid(unsafe_code)] and missing_docs is denied, so every public item carries a doc comment and clippy enforces it.

The engine

src/lib.rs

The datastore. Store, Span, Event, Link, SpanFilter, SpanCursor, Config, CompactionConfig, Durability, Stats, Error.

It owns:

  • the write buffer and its primary-key upsert;
  • the ingest path (ingest, ingest_batch, admit) and the acknowledgement ordering;
  • flushing and segment writing (flush_locked, write_segment);
  • every read path (get_trace, query, query_after, stats), the pinned SnapshotView a multi-page read pages through, and the resolution both share (query_view, attribute_union_view);
  • compaction (compact_segments, merge_tail_run), TTL expiry (compact_expired, expire_before), the maintenance lock that serializes them, and the supersede journal;
  • the single-writer directory lock, including stale-lock reclamation;
  • span↔record conversion and the reserved index keys.

By far the largest file, and the one where the invariants live. Most engine changes start here.

src/segment.rs

The on-disk segment format: encoding, parsing, and file-backed reading. An opened segment owns its file handle, decoded index maps, and a bounded decoded-block cache (four compression blocks, counted by the residency accounting) — records are decoded when a query selects their offsets, and no decoded record vector is retained. Byte layout: segment format.

src/generation.rs

Generations: the one state every recovery domain agrees on. Owns the manifest (state-manifest.json — every load-bearing file with its length and SHA-256, plus the log position it folded through), CURRENT and its staged-rename publication, the digest walk that builds a manifest, verification against one, the staged install behind Store::restore, and the sweep that retires superseded manifests.

The engine’s files never move: a generation references the working set in place, because segment paths are load-bearing (invariants 1 and 5). What changes hands is the manifest. A pin is a hard-link farm of one manifest’s files, which is why a backup copy survives compaction unlinking the originals underneath it.

Store::checkpoint, pin_generation, verify_generation and restore in src/lib.rs are the operations built on this; invariant 12 states the ordering rules they must not break.

src/object_storage.rs (feature object-storage, preview)

The snapshot archive: publishes a verified pin to S3-compatible object storage as an immutable, explicitly named snapshot (manifest written last under a conditional create, every object read back and digest-verified), and reads it back — ranged queries through segment::RangeSource with per-chunk SHA-256 verification under one bounded cache, verified full restore, and snapshot administration. Submodules: manifest (the hostile-input remote manifest), publish, snapshot (the reader; reuses the crate root’s query_view for exact engine semantics), restore, admin, runtime (the dedicated-runtime sync adapter), and testing (the injectable fault backend). Compiled only with --features object-storage; a default build carries none of its dependencies. Operator surface: src/bin/traza-object.rs and the operations guide.

src/migration.rs

The legacy-format migrator (v6 and v7 → v8): automatic at first open, resumable, never in the read path. Owns the FROZEN v6 and v7 decoders (records only, copied from src/segment.rs at 5f23172 and 016eab8 respectively) — the one place the superseded layouts are still understood — each proving exact, gap-free coverage of the record stream rather than trusting the unchecksummed legacy offset index; plus the three-way payload-blob classification, the per-pin file passes and manifest rewrite, and the completion checkpoint (a full re-hash that declares the store format in the manifest). Store::open calls it after crash recovery and before the WAL is replayed; a store whose manifest already declares the format pays a ten-byte version-word read per segment — live and pinned — plus one read of the live manifest inside the trigger. Contract: the Migration section of segment format.

src/wal.rs

The write-ahead log with group commit. The file opens with the 8-byte magic TRZWAL02; framing is [u32 length][u32 crc32][u64 epoch][u64 sequence][payload], the payload being one batch’s JSON. The (epoch, sequence) stamp names the generation a frame was appended under, and recovery replays a frame only when that stamp is strictly after the live generation’s folded_through — see src/generation.rs and invariant 12. Recovery streams frames one at a time and distinguishes a torn tail (bytes the frame declared are missing — dropped, and the file truncated back to the last good frame) from interior damage (a complete frame that fails its checksum or decode — refuses to open, because frames after it may be acknowledged batches). rewrite replaces the log with a given set of spans, which is how retention deletes from the recovery authority rather than only from memory. The fsync runs outside the state lock so concurrent batches coalesce into one sync; a waiter wakes when some sync has covered its LSN.

Also the authoritative statement of the macOS fsync caveat — see durability.

src/payload.rs

Content-addressed offloading of oversized string attribute values to payloads/<aa>/<sha256>.bin, replaced in the span by a $payload reference. Includes a dependency-free SHA-256 (FIPS 180-4) verified against the standard test vectors.

src/annotations.rs

Post-hoc annotations: an append-only JSONL log fsynced per append with an in-memory index by trace. A torn trailing line is ignored, matching the segment layer’s crash-consistency stance.

src/evals.rs

The eval entity model: datasets, versions, examples, experiments, runs — identity and addressing only, deliberately without a runner, a scorer library, or a UI. One append-only JSONL log (evals.jsonl at the store root), fsynced per mutation with the annotation log’s torn-tail healing, wholly resident in memory (datasets are curated artifacts, not span-scale), and rewritten only inside the erasure barrier when a tenant subject purges everything a tenant owns — id floors survive the rewrite so erased dataset and experiment ids are never reissued. Example bodies and version manifests are content-addressed by SHA-256 over the module’s own canonical_json, whose byte form is pinned by test: these digests are persisted identity and must not depend on a dependency’s map-ordering feature flag. Also home to the score aggregation (summarize_scores, diff_scores) behind the experiment summary and diff endpoints.

src/analytics.rs

Sessions and LLM token/cost aggregation — derived views over ordinary spans, no new record type. Holds the per-segment rollup cache (segments are immutable, so a rollup is computed at most once per process and keyed by path) and the supersede prefilter that makes a cached rollup safe to reuse.

src/semconv.rs

Semantic-convention normalization: folds the OpenLLMetry / OTel GenAI vocabulary and Traza’s native llm.* shorthand into one set of facts. A pure function over a span’s attribute map. This is the single source of truth for key precedence — docs/llm-semantics.md documents it and ui/src/lib/spans.js mirrors it, so a change here needs all three to move together.

src/expiration.rs

A four-line placeholder. Expiration is implemented in Store::expire_before in lib.rs; this module reserves the unit and contains no public API.

src/ingest_hooks.rs

The two seams on the ingest path: Store::admission_check, which runs the admission caps and then the tenant quotas before anything about a batch is decided, and Store::observe_admitted, which feeds the run guard once a batch is acknowledged. A batch refused at the first never reaches the second.

src/ledger.rs

The ledger: ledger.jsonl, an append-only hash chain over every published generation, every published erasure (as a salted digest of its subject) and every external anchor, outside generations because it commits to them. Also chain verification, the evidence pack, and the offline verify --ledger. Documented in the ledger guide.

Agent runs

A run is a session id, or trace:<trace_id> for a trace with none (semconv::run_id). These modules read runs; none of them stores anything new about a span.

src/run.rs

Resolves a run id to its spans in step order under the snapshot, erasure mask and query deadline, and pairs step facts with priced LLM facts.

src/guard.rs and src/guard/

Run fuses: policies (policy.rs), the bounded live run state the ingest observer updates (state.rs), the event ring (events.rs), fuses.jsonl for policies, trips, resets and grants (log.rs), and the /v1/fuses/* routes as request → reply functions (http.rs). Documented in the run fuses guide.

src/tape.rs, src/replay.rs, src/diff.rs, src/recall.rs

A run read as a tape of steps; the in-memory replay registry that serves a tape’s model answers back in OpenAI and Anthropic wire shapes; LCS alignment of two tapes and their first divergence; and recall of earlier runs from the content index. Their HTTP routes are in src/bin/traza-server/replay_routes.rs and their MCP tools in src/mcp/replay_tools.rs. Documented in the replay guide.

v0.28: foresight, steering, recorders, X-Ray, radar, TQL, forks

Each is a module with its HTTP handlers beside it (or in a route file under src/bin/traza-server/) and its MCP tool in src/mcp/:

Ingest surfaces

src/otlp.rs

OTLP/HTTP JSON ingest mapping: ExportTraceServiceRequest to Span. Hex ids lowercased, *TimeUnixNano accepted as string or number, typed AnyValue attributes flattened, resource service.name becoming the service, scope attributes merged beneath span attributes.

src/otlp_pb.rs

OTLP/HTTP binary protobuf, hand-rolled and dependency-free. Rather than duplicating the mapping, it lowers protobuf into exactly the JSON Value shape otlp.rs expects and hands off — one mapping, two encodings, so every JSON conformance behaviour applies to protobuf automatically. All slicing is bounds-checked; malformed input yields a decode error, never a panic.

Server-side support

src/auth.rs

The authentication vocabulary — Scope, Principal, and the 401/403 verdicts, each 403 naming the capability it lacked (Required) — and the TRAZA_TOKENS parser. AuthConfig implements a redacted Debug so an accidental structured log cannot disclose credentials, and parse errors name the defect without echoing the value.

src/credentials.rs

The credential set the server authenticates against: environment entries plus runtime credentials, looked up by the SHA-256 of the presented token. Runtime credentials persist in credentials.jsonl (digests only, append-only, torn tail healed), outside generations so backups never carry them.

src/limits.rs, src/usage.rs, src/caps.rs

Per-tenant runtime limits (limits.json: quotas, ingest pause, TTL override), per-tenant usage counters and the quota check (usage.json), and the admission caps plus the one measurement pass ingest makes over a batch. The caps and the quota check run in Store::admission_check; usage is charged at acknowledgement.

src/gzip.rs

A dependency-free inflate (RFC 1951) inside gzip framing (RFC 1952) for Content-Encoding: gzip ingest bodies, with the decompressed size capped by the caller and every member’s CRC-32 and length verified.

src/platform.rs

The hosting state (credentials, limits, usage, one field on Store) and the HTTP handlers for /v1/whoami, /v1/usage and /v1/admin/*, as request → reply functions the server routes to with one call. Also screen, the head-only refusals the gate applies after authentication: cross-site browser requests to admin operations in open mode, and admin bodies not declared JSON.

src/mcp.rs

The Model Context Protocol surface: JSON-RPC framing, initialize and version negotiation, the tool schemas and handlers (the v0.28 tools in src/mcp/), five resources and three URI templates, four prompts, and the renderers that turn spans into something a context window can hold. Tool handlers call Store directly — never back through HTTP — so the module works with no listener in the process at all, which is what tests/mcp.rs relies on.

Two things here are load-bearing rather than cosmetic. sanitize is the only path stored text may take into a result: it escapes control characters and neutralizes the telemetry delimiter, so a span value cannot forge a row or close the untrusted block early. And clamp_report is the last word on size — no result may exceed the configured ceiling, and no truncation may be silent. Documented in the MCP guide.

src/ui.rs

Static serving of the built dashboard from a directory on disk: the discovery order for --ui-dir, the shell routes (/, /dashboard, /dashboard/), content types by extension, and path-traversal refusal against the canonicalized root.

src/metrics.rs

The instrumentation primitives (Counter, Latency) and the engine’s Metrics set, plus Prometheus rendering. Latencies land in power-of-two nanosecond buckets, which is why percentiles are approximate — read the module docs before publishing a number from here. See monitoring.

Test and demo data

src/seed.rs

Deterministic synthetic telemetry: the corpus tests/scenarios.rs asserts against and the seed binary loads. Aims at coverage of real shapes rather than volume — agentic tool-calling traces, all three attribute dialects, multi-turn sessions, multimodal messages, RAG, streaming, failures with linked retries, parallel fan-out, oversized payloads, and ordinary non-LLM traffic. The same options always produce the same corpus byte for byte.

src/media.rs

Synthesized demo media for that corpus — real PNG, GIF, WAV, and SVG bytes encoded from scratch with no image or audio crate, because the dashboard’s media rendering only means anything if the bytes actually decode.

Binaries

src/bin/traza-server.rs

The HTTP/1.1 server: argument parsing, the connection pool and its bound, request framing, the auth gate, route dispatch, chunked export streaming, and server-side metrics. The authoritative source for routes and query parameters — the API reference is checked against this file, not the other way round.

src/bin/traza-object.rs (feature object-storage, preview)

The archive CLI: pin (offline, exclusive), publish, list, inspect, verify, query/trace/payload, restore, delete, cleanup. Credentials come from the standard AWS environment, never flags. Built only with --features object-storage.

src/bin/bench.rs

The canonical end-to-end benchmark. Builds and starts the release server, drives it over HTTP, and rewrites canonical-corpus.md from its own measurements.

src/bin/ingest-bench.rs

The ingest matrix over protocol, keep-alive, concurrency, and durability. Reports the median of N runs with its spread and refuses to report a rate from a run that shed a connection or stored fewer spans than it acknowledged.

src/bin/seed.rs

Loads the seed corpus, either directly through the engine (--data-dir) or over HTTP into a running server (--url). Two modes because a data directory has exactly one writer.

Elsewhere in the tree

Path What it is
tests/ Integration tests — see testing
ui/ The React dashboard; npm run build emits ui/dist
ci.sh The merge gate
docs/ This documentation set