Weaviate

Available for: Python and TypeScript.

Calling Weaviate directly (no LangChain/LlamaIndex retriever abstraction in between) previously got zero automatic tracing — only the manual recordRetrieval/record_retrieval helper. Zespan now patches the v4 collections client (Python) / weaviate-client v3 (Node) so every near_vector query and data.insert() 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 — collection.query.near_vector() (Python) / collection.query.nearVector() (Node) emits a retriever span. This is the v4-style, method-based collections API (gRPC transport) — the older GraphQL builder chain (.withNearVector().withLimit().do()) is not patched
Writes — collection.data.insert() (single object, REST transport) emits an embedding span. Batch insert methods are not patched

Python
TypeScript

Installation

pip install zespan weaviate-client

Usage

import zespan

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

import weaviate

client = weaviate.connect_to_local()
collection = client.collections.get("Docs")

# Traced automatically -- emits an "embedding" span
collection.data.insert(properties={"text": "chunk text", "source": "handbook.pdf"})

# Traced automatically -- emits a "retriever" span
results = collection.query.near_vector(near_vector=query_embedding, limit=5)

Only the sync Weaviate client is auto-traced. WeaviateAsyncClient (the async client) is not yet covered — if you’re on the async client, use the manual record_retrieval/record_vector_search helpers instead.

Installation

npm install @zespan/sdk weaviate-client

Usage

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

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

import weaviate from "weaviate-client";

const client = await weaviate.connectToLocal();
const collection = client.collections.get("Docs");

// Traced automatically -- emits an "embedding" span
await collection.data.insert({ text: "chunk text", source: "handbook.pdf" });

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

weaviate-client’s collection objects come from plain factory functions, not a class with a shared prototype — patching a prototype once (the pattern every other Node wrapper uses) would do nothing here. Zespan instead patches client.collections.get()/.use()/.create() (and the connectToLocal/connectToWeaviateCloud/connectToCustom entry points that produce the client) so that each returned collection’s own query.nearVector/data.insert are patched directly. This is transparent to your code — every collection you obtain through get(), use(), or create() is traced.

What gets captured

Read span (`near_vector`) — `span_kind: "retriever"`, `operation: "vector_search"`

Field	Details
`provider`	`"weaviate"`
`latency_ms`	Time spent in the real `near_vector`/`nearVector` call
`status`	`"success"` or `"error"` (with `error_message`, truncated to 500 characters)
`rag_context_count`	Number of objects returned
`metadata.rag_contexts`	One entry per object: `{ content, document_id, score, source }` — `content` comes from the object’s properties (its text field), `document_id` from the object’s UUID, `score` from `metadata.score`, falling back to `certainty` then `distance` depending on which the query requested. 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 Weaviate’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 `filters` 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 object text is dropped while document_id/source/score are still kept.

Write span (`data.insert()`) — `span_kind: "embedding"`, `operation: "vector_upsert"`

Field	Details
`provider`	`"weaviate"`
`metadata.vector_count`	Always `1` — only the single-object `insert()` is patched, not a batch insert method. 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 `insert()` call
`input_tokens`	Always `0` — the wrapper doesn’t generate embeddings, it only records that an object was written
`status`	`"success"` or `"error"` (with `error_message`)

Linking a Weaviate query to a following LLM call. Trace context (trace_id) is picked up from whatever with_zespan_context()/withZespanContext() scope is active when near_vector/insert() runs — the same rule every other Zespan wrapper follows. If your Weaviate 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, Qdrant — 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 (`near_vector`) — `span_kind: "retriever"`, `operation: "vector_search"`

Write span (`data.insert()`) — `span_kind: "embedding"`, `operation: "vector_upsert"`

Next steps

​What gets traced

​Installation

​Usage

​Installation

​Usage

​What gets captured

​Read span (near_vector) — span_kind: "retriever", operation: "vector_search"

​Write span (data.insert()) — span_kind: "embedding", operation: "vector_upsert"

​Next steps

What gets traced

Installation

Usage

Installation

Usage

What gets captured

Read span (`near_vector`) — `span_kind: "retriever"`, `operation: "vector_search"`

Write span (`data.insert()`) — `span_kind: "embedding"`, `operation: "vector_upsert"`

Next steps