Skip to main content
When an answer goes wrong, the first question is which layer failed: the instructions, retrieval, memory, a tool, or the model. Zespan can only answer that when it knows what went into the prompt. Context segments tell it: you mark a piece of text as rag, memory, tool, user, system or example, and Zespan records where that text sat in the prompt, never the text itself.
Available for: TypeScript and Python. Same fields and behavior in both.

What leaves your process

For every segment found in a model call, the SDK sends only: The text is located inside your process, against the request you send, before redaction or capture settings are applied. These fields are content-free, so they are kept even with storePrompts: false. The segment text itself is stored only where prompt capture already stores it.

Mark a segment

segment() returns the text you passed (the same value), so it drops into existing code. segments() marks several texts at once. Nothing here throws into your code: a bad argument leaves the text unmarked. A segment is attached to a model call only when its exact text appears in that call’s messages. Segments you mark but never use are not reported, so a stray mark never produces a false finding.
Marked segments wait in a pool per trace. Calls running at the same time in one trace, or in a process with no trace context, share that pool: when two of them mark the same text with different document ids, Zespan cannot tell whose document a call used. Give each request its own trace (withZespanTrace / with_zespan_trace) to keep them apart. Each trace holds at most 64 pending segments; a segment beyond that is not attached (it is never reported as missing).

Report segments that never reached the prompt

Wrap a request in a scope when you want to know about documents that were retrieved but dropped before the prompt was built (for example by a token budget):
When the scope ends, segments registered inside it that a model call made inside the scope looked for and did not find are reported as located: false with scoped: true. This is the only way a segment is ever reported as not found. A scope in which no model call ran (for example because your code failed first), or in which only one of our framework integrations made the call (they link their own segments by run id), reports nothing: nothing is known about those segments.

Threads and workers

Segments follow your trace context. They do not cross a thread that does not carry the context:
  • Python: asyncio.to_thread copies the context. For loop.run_in_executor and ThreadPoolExecutor.submit, wrap the function: pool.submit(zespan.context.bind(work)).
  • TypeScript: a worker thread has its own memory. Call zespan.context.exportSegments() in the main thread and zespan.context.importSegments(handoff) in the worker.

Automatic tagging in our integrations

Our LangChain, LlamaIndex, Google ADK, Haystack and Semantic Kernel integrations tag retrieved documents, tool results and recalled memory for you, linked through the framework’s own run ids, so two requests running at once never hand each other segments. These tags carry auto: true and metadata only. Turn auto-tagging off with contextAutoTag: false (TypeScript), context_auto_tag=False (Python), or the environment variable ZESPAN_CONTEXT_AUTOTAG=off. The setting is read on every call.

Retrieval metadata

Retriever spans from the Pinecone, Chroma, Qdrant and Weaviate auto-patch, the LangChain, LlamaIndex, Haystack and vectra integrations, recordRetrieval / record_retrieval, and OpenInference retrieval spans sent over OTLP carry content-free retrieval metadata: Reranker spans (Cohere rerank, LangChain compression and rerank retrievers, and in Python LlamaIndex postprocessors and Haystack rankers) carry zespan.rerank.in_ids, out_ids, out_scores and top_n. All of these survive storePrompts: false. Retrieved documents are stored as objects with a document id; a document without one gets a stable generated id.

Next steps

Manual spans

Record retrieval and custom steps yourself.

Prompt management

Link model calls to the prompt version they used.

Span kinds

Retriever and reranker spans in the trace tree.

PII redaction

What is redacted before data leaves your process.