Qdrant

Available for: Python and TypeScript.

Calling Qdrant directly (no LangChain/LlamaIndex retriever abstraction in between) previously got zero automatic tracing — only the manual recordRetrieval/record_retrieval helper. Zespan now patches QdrantClient so every query and upsert() call is captured automatically, the same way LLM provider calls already are.

Patched automatically as part of zespan.autopatch(), which both SDKs run on init() unless you pass autopatch: false (autopatch=False in Python). There’s no separate opt-in call for vector-DB tracing.

What gets traced

Reads — Python: query_points() only, on both QdrantClient (sync) and AsyncQdrantClient. The Python client’s .search() method was removed entirely in current qdrant-client versions, so there’s nothing to patch there. Node: both client.search() and client.query() are patched — the JS client still ships both methods, so either style is traced
Writes — upsert() (sync and async in Python; single method in Node) emits an embedding span

Python
TypeScript

Installation

pip install zespan qdrant-client

Usage

import zespan

zespan.init(api_key="zsp_your_api_key_here")  # patches Qdrant automatically

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

# Traced automatically -- emits an "embedding" span
client.upsert(
    collection_name="docs",
    points=[{"id": "doc1", "vector": doc_embedding, "payload": {"text": "chunk text", "source": "handbook.pdf"}}],
)

# Traced automatically -- emits a "retriever" span
results = client.query_points(collection_name="docs", query=query_embedding, limit=5)

AsyncQdrantClient is patched the same way — await client.query_points(...) and await client.upsert(...) are traced identically to the sync calls above.

Installation

npm install @zespan/sdk @qdrant/js-client-rest

Usage

import { zespan } from "@zespan/sdk";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! }); // patches Qdrant automatically

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ url: "http://localhost:6333" });

// Traced automatically -- emits an "embedding" span
await client.upsert("docs", {
  points: [{ id: "doc1", vector: docEmbedding, payload: { text: "chunk text", source: "handbook.pdf" } }],
});

// Traced automatically -- emits a "retriever" span
const results = await client.query("docs", { query: queryEmbedding, limit: 5 });

// Also traced -- client.search() is patched too, for apps still on the older style
const legacyResults = await client.search("docs", { vector: queryEmbedding, limit: 5 });

What gets captured

Read span (`query_points()` / `query()` / `search()`) — `span_kind: "retriever"`, `operation: "vector_search"`

Field	Details
`provider`	`"qdrant"`
`latency_ms`	Time spent in the real call
`status`	`"success"` or `"error"` (with `error_message`, truncated to 500 characters)
`rag_context_count`	Number of points returned
`metadata.rag_contexts`	One entry per point: `{ content, document_id, score, source }` — `content` comes from the point’s payload (its text field), `document_id` from the point id, `score` from the point’s similarity score. Same shape `recordRetrieval`/`record_retrieval` produces, so the trace-detail Retrieval panel and the RAG evaluators work with no extra setup
`metadata.top_k`	Requested result count, read from the call’s `limit` option — only present when you actually pass one, since `limit` is optional in Qdrant’s client. Not gated by `storePrompts` when present, since it’s a count, not query content. Only observable nested under `metadata` — the ingest pipeline persists the `metadata` object verbatim but drops other unrecognized top-level fields
`metadata.filter`	The query’s `filter`/`query_filter` option, redacted and stringified — only present when `storePrompts`/`store_prompts` is `true` (its default). Filter values commonly carry user IDs, emails, or other PII, so unlike `top_k` this is dropped entirely, not just redacted, when `storePrompts` is off. (Same `metadata`-only visibility as `top_k` above.)

content follows your storePrompts/store_prompts setting and the same redaction rules as prompt text — set storePrompts: false and payload text is dropped while document_id/source/score are still kept.

Write span (`upsert()`) — `span_kind: "embedding"`, `operation: "vector_upsert"`

Field	Details
`provider`	`"qdrant"`
`metadata.vector_count`	Number of points in the `upsert()` call. Only observable nested under `metadata` — the ingest pipeline persists the `metadata` object verbatim but drops other unrecognized top-level fields
`latency_ms`	Time spent in the real `upsert()` call
`input_tokens`	Always `0` — the wrapper doesn’t generate embeddings, it only records that vectors already computed elsewhere were upserted
`status`	`"success"` or `"error"` (with `error_message`)

Linking a Qdrant query to a following LLM call. Trace context (trace_id) is picked up from whatever with_zespan_context()/withZespanContext() scope is active when the query/upsert() runs — the same rule every other Zespan wrapper follows. If your Qdrant call and your LLM call are two independent, unwrapped top-level calls, they land on two different traces, and RAG evaluators/the Retrieval panel won’t see the connection between them. Wrap both in the same with_zespan_context()/withZespanContext() block, exactly like the complete RAG pipeline example in Manual spans.

Next steps

Manual spans — the record_vector_search()/recordVectorSearch() helper for pgvector, and the full with_zespan_context()/withZespanContext() trace-linking pattern
Evaluating RAG pipelines — score retrieval quality once rag_contexts is on the trace
Pinecone, Chroma, Weaviate — the other auto-traced vector DBs

Overview

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Vector Databases

Custom / Other

Guides

What gets traced

Installation

Usage

Installation

Usage

What gets captured

Read span (`query_points()` / `query()` / `search()`) — `span_kind: "retriever"`, `operation: "vector_search"`

Write span (`upsert()`) — `span_kind: "embedding"`, `operation: "vector_upsert"`

Next steps

​What gets traced

​Installation

​Usage

​Installation

​Usage

​What gets captured

​Read span (query_points() / query() / search()) — span_kind: "retriever", operation: "vector_search"

​Write span (upsert()) — span_kind: "embedding", operation: "vector_upsert"

​Next steps

What gets traced

Installation

Usage

Installation

Usage

What gets captured

Read span (`query_points()` / `query()` / `search()`) — `span_kind: "retriever"`, `operation: "vector_search"`

Write span (`upsert()`) — `span_kind: "embedding"`, `operation: "vector_upsert"`

Next steps