> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Weaviate (tracing)

> Trace Weaviate v4 collection, data, query, aggregate, and batch operations with Respan.

[Weaviate](https://weaviate.io/) 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](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

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

#### Example projects

* [Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/weaviate)

#### Tracing

## Setup

#### Install packages

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

#### Set environment variables

```bash
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](https://platform.respan.ai/platform/traces) 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. |