Weaviate (tracing) | Respan Docs

Weaviate is an open-source vector database that stores objects and vectors and supports vector, BM25, and hybrid retrieval. The Respan-owned Weaviate instrumentation traces the Python v4 collection API across synchronous and asynchronous clients and supports weaviate-client>=4.22.0,<5.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Python examples

Tracing

Setup

Install packages

$ pip install respan-ai respan-instrumentation-weaviate "weaviate-client>=4.22.0,<5"

Set environment variables

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

RESPAN_API_KEY exports traces to Respan. The quickstart expects a local Weaviate instance on HTTP port 8080 and gRPC port 50051.

Initialize and run

1 import os
2 
3 import weaviate
4 from respan import Respan, workflow
5 from respan_instrumentation_weaviate import WeaviateInstrumentor
6 from weaviate.classes.config import Configure, DataType, Property
7 from weaviate.classes.query import MetadataQuery
8 
9 respan = Respan(
10     api_key=os.environ["RESPAN_API_KEY"],
11     instrumentations=[WeaviateInstrumentor()],
12 )
13 
14 
15 @workflow(name="weaviate_data_and_queries_workflow")
16 def run_weaviate_query():
17     client = weaviate.connect_to_local()
18     collection_name = "RespanDocs"
19 
20     if client.collections.exists(collection_name):
21         client.collections.delete(collection_name)
22 
23     collection = client.collections.create(
24         collection_name,
25         properties=[
26             Property(name="text", data_type=DataType.TEXT),
27             Property(name="topic", data_type=DataType.TEXT),
28         ],
29         vector_config=Configure.Vectors.self_provided(),
30     )
31 
32     try:
33         collection.data.insert(
34             {
35                 "text": "Respan traces Weaviate vector operations.",
36                 "topic": "observability",
37             },
38             vector=[0.9, 0.1, 0.0, 0.0],
39         )
40         collection.data.insert(
41             {
42                 "text": "Weaviate supports vector and hybrid retrieval.",
43                 "topic": "search",
44             },
45             vector=[0.2, 0.8, 0.0, 0.0],
46         )
47 
48         return collection.query.near_vector(
49             near_vector=[0.85, 0.15, 0.0, 0.0],
50             limit=2,
51             return_metadata=MetadataQuery(distance=True),
52         )
53     finally:
54         client.collections.delete(collection_name)
55         client.close()
56 
57 
58 result = run_weaviate_query()
59 for obj in result.objects:
60     print(obj.properties, obj.metadata.distance)

View your trace

Open the Traces page and search for workflow name weaviate_data_and_queries_workflow.

Covered operations

The instrumentor covers Weaviate v4 collection lifecycle, object and reference mutations, vector, BM25, and hybrid queries, aggregates, collection configuration, batch writes, tenants, and matching asynchronous managers. Generative search is not mapped as a vector-database task because it requires separate LLM chat semantics.

Content capture

Operation arguments and results are captured by default. Disable them when vectors, object properties, or query results should not be attached to spans:

1 from respan import Respan
2 from respan_instrumentation_weaviate import WeaviateInstrumentor
3 
4 respan = Respan(
5     instrumentations=[WeaviateInstrumentor(capture_content=False)],
6 )

Operation names, status, and database attributes remain available when content capture is disabled.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to the `RESPAN_API_KEY` environment variable.
`base_url`	`str \| None`	`None`	Falls back to the `RESPAN_BASE_URL` environment variable.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate, such as `WeaviateInstrumentor()`.
`capture_content`	`bool`	`True`	`WeaviateInstrumentor` option that controls operation argument and result capture.
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag, such as `"production"`.

Attributes

In Respan()

1 from respan import Respan
2 from respan_instrumentation_weaviate import WeaviateInstrumentor
3 
4 respan = Respan(
5     instrumentations=[WeaviateInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "weaviate-rag-api", "version": "1.0.0"},
8 )

With propagate_attributes

1 from respan import propagate_attributes
2 
3 
4 def search(collection, user_id: str, query_vector: list[float]):
5     with propagate_attributes(
6         customer_identifier=user_id,
7         thread_identifier="weaviate_thread",
8         metadata={"collection": collection.name, "plan": "pro"},
9     ):
10         return collection.query.near_vector(
11             near_vector=query_vector,
12             limit=2,
13         )

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related operations into a thread.
`metadata`	`dict`	Custom key-value pairs merged with default metadata.