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.
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):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_threadcopies the context. Forloop.run_in_executorandThreadPoolExecutor.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 andzespan.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 carryauto: 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.

