What to log in an AI system so you can debug it later

What to log in an AI system, in one paragraph

The test for whether your logging is adequate has nothing to do with volume. It is whether a colleague, handed only a customer complaint and a trace id, can reconstruct what the system saw and why it answered the way it did, six weeks later, without asking anyone. Most AI logging fails that test not because it is thin but because it is unjoinable: the model call is in one place, the retrieval in another, the human's correction in a product database, and no field connects them.

The Replay Record

The two record levels matter. Run level is what you query in aggregate: one row per unit of work with the totals, the terminal state and the outcome. Call level is what you read during an investigation: the full detail of each step. Putting everything at call level makes aggregate queries expensive, and putting everything at run level makes debugging impossible, which is why systems that logged only one of the two end up rebuilding both anyway.

The record, as JSON you can copy

{
  "schema": "llm_call/v1",
  "ts": "2026-08-26T09:41:12.884Z",
  "env": "prod",
  "release": "9f3c1ab",

  "trace_id": "01J9Z7QK4M2X",        // one id from trigger to outcome
  "run_id": "run_8f21",
  "call_id": "call_3",
  "parent_call_id": "call_2",
  "tenant_id": "t_1042",
  "user_ref": "u_9c1f8b",            // pseudonymous, never an email
  "surface": "support_reply_draft",

  "prompt": {
    "template_id": "support_reply",
    "version": 7,
    "sha256": "b41d0f9c...",         // resolves in the prompt registry
    "vars": {
      "ticket_id": "T-88213",
      "customer_name": "[REDACTED:name]",
      "locale": "en-GB"
    },
    "assembled_tokens": 3411         // catches silent context truncation
  },

  "model": {
    "requested": "vendor/model-alias",
    "returned": "vendor/model-alias-2026-07-11",   // log what came back
    "temperature": 0.2,
    "top_p": 1,
    "max_tokens": 800,
    "seed": null
  },

  "retrieval": {
    "index": "kb_support",
    "index_version": "2026-08-25T02:10Z",
    "k_requested": 8,
    "k_returned": 8,
    "reranker": "rr_v3",
    "newest_doc_ts": "2026-08-24T17:02Z",
    "chunks": [
      {"id": "kb:3391#c07", "doc_version": 14, "score": 0.81, "rank_final": 1},
      {"id": "kb:1180#c02", "doc_version": 9,  "score": 0.74, "rank_final": 2}
    ]
  },

  "tools": [
    {"name": "lookup_order", "args": {"order_id": "A-4417"}, "args_source": "model",
     "status": "ok", "latency_ms": 212, "result_sha256": "77a1c2d0..."},
    {"name": "issue_refund", "args": {"order_id": "A-4417", "amount": 41.5},
     "args_source": "model", "status": "blocked_by_policy", "latency_ms": 3,
     "policy": "refund_ceiling"}
  ],

  "output": {
    "raw_sha256": "0ac9e14b...",
    "raw_ref": "blob://outputs/2026/08/26/run_8f21_call_3",
    "parsed_ok": true,
    "validation": {"ok": false, "failing_paths": ["$.next_action"]},
    "guardrails_fired": ["pii_in_output"],
    "finish_reason": "stop"
  },

  "usage": {
    "input_tokens": 3411,
    "cached_input_tokens": 2800,
    "output_tokens": 240,
    "price_snapshot": "prices/2026-08-01.json",   // never hardcode a price here
    "cost": null                                   // filled by a job that reads the snapshot
  },

  "retry": {"attempt": 1, "of": 3, "previous_call_id": null, "reason": null},
  "latency_ms": 1840,

  "outcome": {                       // written back later, joined on trace_id
    "state": "edited",
    "by": "u_31aa",
    "at": "2026-08-26T09:47:02Z",
    "edit_distance": 34,
    "reason_code": "tone"
  }
}

Three details in that record are worth naming because they are the ones teams leave out and then wish they had. The returned model identity, because providers move aliases and a quality shift with no deploy in your repository is almost always this. The assembled token count, because it is the only cheap detector for context truncation silently dropping the front of your prompt. And args_source on every tool call, distinguishing the arguments the model generated from the arguments your code substituted, because the delta between those two is where a surprising number of agent bugs live.

Log the prompt by reference, not by value

Store prompt text once in a registry keyed by content hash, and put the hash on the call record. The instinct to paste the full assembled prompt into every log line is understandable and it is wrong on cost, on privacy and, counterintuitively, on reproducibility.

Retrieval provenance is the field everyone skips

In a retrieval system, the first question about any wrong answer is whether the right evidence was retrieved and ignored, or never retrieved at all. Those two failures have completely different fixes, and you cannot distinguish them after the fact unless the chunk ids were logged at the time. Adding this field later does not help, because it cannot be backfilled.

• Chunk ids with scores and final rank tell you whether the correct passage was in the candidate set. If it was retrieved at rank nine and your k is eight, the fix is retrieval configuration. If it was retrieved at rank one and the answer ignored it, the fix is in the prompt or the model.
• Document version per chunk tells you which revision of the policy the answer was based on. Without it, a customer disputing an answer becomes an argument, because the document has since been edited and the current text supports neither party.
• Index version and newest document timestamp turn a stale answer from a mystery into a one line query. This is also the field that powers the freshness alert described in monitoring an AI system in production.
• Reranker identity and the order before and after reranking catch the case where retrieval was correct and the reranker demoted the right passage. This is a real and frequent failure, and it is completely invisible if you log only the final order.
• k requested against k returned catches partial index failures, filter conditions that excluded everything, and permission filters that silently removed the only relevant document for that user.

Log ids and scores rather than chunk text. The text is reconstructible from the id plus the document version, it is often personal or confidential, and it is by a wide margin the largest thing you could put in the record. If you cannot reconstruct a chunk from its id and version, that is a gap in your document store, not a reason to duplicate the corpus into your log pipeline. That is a gap worth closing in the document store itself.

What must never be written down

Logging is the most common way personal data escapes an AI system, because logs get shipped to third party observability vendors, replicated to analytics warehouses, read by contractors during incidents, and retained far past the point anyone remembers what is in them. Decide the rules before the first record is written, and enforce them in code rather than in a policy document.

Retention should be tiered rather than uniform. Skeleton records with ids, metrics and verdicts are small, and keeping them for a year costs little and answers most questions. Full payloads, meaning raw outputs and variable values, are large and sensitive, and a much shorter window covers the debugging need. The legal and consent side of this is the subject of personal data in AI pipelines, and the decision record side, where you must be able to justify an automated decision later, is in making agent decisions auditable.

What this costs, and where to sample

Log volume in an AI system is dominated by payloads, not by metadata. A skeleton record is a few kilobytes. A record carrying the assembled prompt, the retrieved chunk text and the full completion can be two orders of magnitude larger, and it is the same record. That is why the sampling decision is not about whether to log but about which parts of the record to keep for everything and which parts to keep for a slice.

Compare the last two outputs and the sampling policy writes itself. The rule that works in practice is to keep the skeleton record for every single call with no sampling at all, and keep the full payload for a random slice plus every run in four categories: anything where validation failed, anything where a guard rail fired, anything a human overrode or escalated, and anything flagged by a customer. Those four categories are exactly the runs you will want to read, they are a small share of traffic, and a random slice on top of them stops the kept set from being a biased view of only the failures.

Cardinality, or the log field that takes down the dashboard

Logs, traces and metrics have different rules and the difference is cardinality. A log line can carry any number of unique values. A metric label cannot, because most time series systems create one series per unique combination of labels, and a single unbounded label turns a cheap counter into millions of series and a very expensive Tuesday.

• Never put trace_id, run_id, user_ref, prompt hash, document id or any free text into a metric label. Those belong in logs and traces, which are built for them.
• Bounded label sets that are safe: model identity, template id, tool name, outcome class, guard rail name, tenant tier, environment, and validation pass or fail.
• tenant_id is the borderline case. It is fine with tens of tenants and dangerous with tens of thousands. Use tenant tier as the label and keep the exact tenant in the log record, then query logs when you need per tenant detail.
• Validation failure paths are safe as labels only if the schema is fixed and small. If the path can contain an array index, normalise it before it becomes a label or you have unbounded cardinality by another route.
• Error strings from providers are never safe as labels, because they frequently contain request ids. Map them to a small enumerated class at the boundary and label with the class.

The practical rule is to decide, for every field in the replay record, whether it is a log field, a trace attribute, a metric label, or all three, and write that decision into the schema definition rather than leaving it to whoever adds the next instrumentation line. This is a five minute exercise that prevents a category of incident which is tedious to diagnose and embarrassing to explain.

Design the schema backwards from the questions you will ask

The schema is correct when it answers the questions that actually get asked under pressure, and those questions are remarkably consistent across systems. Write them down first, then check that each one is a query rather than an investigation. Any question that cannot be answered by a query is a missing field, and it is far cheaper to add now than after the incident that needed it.

1. Show me the full trace for this complaintneeds: trace id surfaced on the customer facing artifact

   The customer has a reference number and you need every step behind it. This fails when the trace id lives only in your backend and never reaches the ticket, the email, the document or the interface, which means the support agent has to guess at timestamps. Put the trace id somewhere visible, even if it is an HTML comment or a small grey string in a footer.

2. Show me every run that used prompt version 7needs: template id and prompt hash on every call

   You changed a prompt and want the blast radius, or you found a defect and want to know who received it. Without the version and hash on the call record this becomes a reconstruction from deploy timestamps, which is approximate at exactly the moment approximate is not acceptable.

3. Show me every failure grouped by failing schema pathneeds: structured validation results, not message strings

   Validation errors stored as prose cannot be grouped, so a single dominant failure mode hides inside forty slightly different strings. Store the failing path as an array of strings and the grouping is a query. This one field changes debugging a structured output system more than any other.

4. Show me every run that retrieved document Xneeds: chunk ids in an indexed array field

   A document turns out to be wrong and you need every answer that relied on it, for correction or for notification. This is a legal requirement in some settings and it is impossible without chunk ids at call time. Index the array, because a full scan across months of logs is the difference between a query and a project.

5. Show me cost by tenant last week, split by templateneeds: tokens, price snapshot, tenant id and template id together

   Cost attribution is asked for by finance and by whoever is deciding what to optimise. Storing the price snapshot reference rather than a computed figure means a price change does not rewrite history, and it also means you never hardcode a number that goes stale.

6. Show me every result a human edited, with the diffneeds: the outcome write back

   This is the query that builds your evaluation set, sizes the real quality problem, and tells you which parts of the output people never trust. It is the smallest amount of instrumentation on this list and it is the one most often missing, because it lives in the product interface rather than in the AI code.

If a question on that list would take you more than a minute to answer today, the fix is a field, not a dashboard. Building this properly across an agent that fans out across many tools is the substance of agent observability.

Definitions, and the logging checklist

Definitions

Correlation id

A single identifier generated at the triggering event and carried through every model call, tool call, retry and downstream write for that unit of work, including outcome records written days later. It is what makes logs from separate systems joinable into one story.

Replayable run

A logged run containing enough detail to reconstruct what the system saw and produced without access to the original process: prompt by hash, model identity, sampling parameters, retrieval set, tool calls with arguments, raw output and verdict.

Retrieval provenance

The record of which chunks were retrieved for a run, with their document ids, document versions, similarity scores and final rank after reranking. It is what separates a retrieval failure from a generation failure, and it cannot be backfilled.

Redaction at the edge

Removing or tokenising sensitive values in the client wrapper that constructs the log record, so raw personal data never exists in the record object, in a buffer, or in a stack trace. Redaction applied later in the pipeline has already failed.

Cardinality

The number of distinct values a field can take. High cardinality fields such as identifiers and free text belong in logs and traces. Metric labels need bounded, low cardinality values, because most time series databases create one series per unique label combination.

Skeleton record

The small always-logged part of a call record holding ids, versions, counts, timings and verdicts but no payload text. It is cheap enough to keep for every call with no sampling, and it answers most aggregate questions on its own.

One closing warning about sequencing. Every field in the replay record is cheap to add on day one and expensive to add on day two hundred, because the value of a log is entirely historical and you cannot backfill history. The teams that regret their logging are never the ones who logged a slightly larger record than they needed. They are the ones who discovered in an incident that the one field which would have answered the question was the field nobody thought to write.