Weaviate (tracing)

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 .

Paste this into your coding agent:


Help me set up Respan tracing with the Weaviate integration.
Follow https://www.respan.ai/docs/integrations/weaviate.md

Setup

Install packages

Terminal


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

Set environment variables

Terminal


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

Python


import os

import weaviate
from respan import Respan, workflow
from respan_instrumentation_weaviate import WeaviateInstrumentor
from weaviate.classes.config import Configure, DataType, Property
from weaviate.classes.query import MetadataQuery

respan = Respan(
    api_key=os.environ["RESPAN_API_KEY"],
    instrumentations=[WeaviateInstrumentor()],
)


@workflow(name="weaviate_data_and_queries_workflow")
def run_weaviate_query():
    client = weaviate.connect_to_local()
    collection_name = "RespanDocs"

    if client.collections.exists(collection_name):
        client.collections.delete(collection_name)

    collection = client.collections.create(
        collection_name,
        properties=[
            Property(name="text", data_type=DataType.TEXT),
            Property(name="topic", data_type=DataType.TEXT),
        ],
        vector_config=Configure.Vectors.self_provided(),
    )

    try:
        collection.data.insert(
            {
                "text": "Respan traces Weaviate vector operations.",
                "topic": "observability",
            },
            vector=[0.9, 0.1, 0.0, 0.0],
        )
        collection.data.insert(
            {
                "text": "Weaviate supports vector and hybrid retrieval.",
                "topic": "search",
            },
            vector=[0.2, 0.8, 0.0, 0.0],
        )

        return collection.query.near_vector(
            near_vector=[0.85, 0.15, 0.0, 0.0],
            limit=2,
            return_metadata=MetadataQuery(distance=True),
        )
    finally:
        client.collections.delete(collection_name)
        client.close()


result = run_weaviate_query()
for obj in result.objects:
    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:

Python


from respan import Respan
from respan_instrumentation_weaviate import WeaviateInstrumentor

respan = Respan(
    instrumentations=[WeaviateInstrumentor(capture_content=False)],
)

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()

Python


from respan import Respan
from respan_instrumentation_weaviate import WeaviateInstrumentor

respan = Respan(
    instrumentations=[WeaviateInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "weaviate-rag-api", "version": "1.0.0"},
)

With propagate_attributes

Python


from respan import propagate_attributes


def search(collection, user_id: str, query_vector: list[float]):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="weaviate_thread",
        metadata={"collection": collection.name, "plan": "pro"},
    ):
        return collection.query.near_vector(
            near_vector=query_vector,
            limit=2,
        )

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.