Skip to content

Reference

Architecture

How a trace gets from your app to a diagnosis in the dashboard, and what is stored on the way.

The path of a trace#

One query
Your app → API → Rule engine → Dashboard
  1. Your app. The SDK records each retrieval stage and builds one trace.
  2. API. Checks your key, validates the trace, stores it, and queues a diagnosis.
  3. Rule engine. Reads the stored trace and writes its findings next to it.
  4. Dashboard. Lists your traces and draws each one stage by stage.

Where each part runs:

Part Name Runs
SDK @chunktrace/sdk In your process
API api.chunktrace.com Hosted
Rule engine @chunktrace/core Hosted, and anywhere else you run it
Dashboard chunktrace.com In your browser

In your app#

The SDK wraps the calls you already make: retrieve, rerank, build the context, answer. As each one runs, it notes what went in and what came out.

Three things happen here and nowhere else:

  • The shadow query. With diagnose mode on, the SDK asks your store a second time with no filter and no threshold. That is how a later diagnosis can prove what your settings removed.
  • Label matching. The SDK checks each chunk against your label and records a yes or no. Chunk text stays in your process unless you choose to send it.
  • Building the trace. finish() assembles one JSON document and hands it to your sink.

The SDK makes no network calls of its own. Only the sink sends anything, and httpSink never throws: if the API can't be reached, your app still answers the query and the error goes to onError.

Ingestion#

POST /v0/traces does four things before it replies:

  1. Checks the key. A key belongs to one project. Only a hash of its secret is stored, so the secret can't be read back.
  2. Validates the trace against the trace schema. Fields the schema doesn't know are dropped. A trace that passes can always be diagnosed.
  3. Stores the trace once. A trace_id is unique within a project, so a retry is answered with duplicate and changes nothing.
  4. Queues a diagnosis in the same step as the save. A stored trace always has a diagnosis on the way.

Then it replies 202. Your app never waits for the diagnosis.

Diagnosis#

A worker takes the queued job, runs the rule engine on the stored trace, and saves the result beside it: the findings, the primary finding's code, and the engine version. The trace's status goes from queued to diagnosed, usually within a second or two.

The engine is a pure function. It reads the trace and nothing else: no model, no network, no other traces. How a diagnosis works describes the rules.

If a job fails, it is retried after a growing delay. A trace whose diagnosis keeps failing is marked failed, and stays readable.

What is stored#

Stored Detail
The trace The JSON you sent, after validation.
The diagnosis Findings and their evidence, the primary code, the engine version, and when it ran.
API keys A name, a scope, and a hash of the secret.
Your account Your email address and a hash of your password.

The trace is the record. The diagnosis is derived from it, and can be worked out again from the trace alone.

Reading it back#

The dashboard has no rules of its own. It asks the API for a trace, its diagnosis and its stage-by-stage timeline, and draws what comes back. A stage is marked Evidence lost here because the engine said so.

Anything the dashboard shows, a read-only key can fetch. Both see one project and nothing outside it.

Why it is built this way#

  • Same trace, same answer. With rules instead of a model, a diagnosis doesn't change between runs, and every finding points at the values that prove it.
  • One engine everywhere. run.diagnose() in your process, the CLI and the server run the same code. A verdict in a test is the verdict in production.
  • Your app comes first. Tracing happens in your process and sending fails quietly. An outage here costs you a trace, not an answer.
  • The trace is enough. Everything a diagnosis needs is in the trace, so a saved trace file is a complete, replayable record.