Registry /
observability / opentelemetry-instrumentation-weaviate
Install & Compatibility
Where this runs
tested against v0.62.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.470s · 87.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.3s · import 0.416s · 85MB
86MB installed
● package 86MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WeaviateInstrumentor
✓ from opentelemetry.instrumentation.weaviate import WeaviateInstrumentor
This quickstart demonstrates how to set up OpenTelemetry tracing with `opentelemetry-instrumentation-weaviate`. It initializes a console exporter, instruments the Weaviate client, and then attempts to connect to a Weaviate instance, showing where your traced operations would occur. Ensure you have a Weaviate instance running locally or a Weaviate Cloud Service (WCS) instance configured with your URL and API key.
import os
import weaviate
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.weaviate import WeaviateInstrumentor
# 1. Setup OpenTelemetry TracerProvider and Exporter
resource = Resource.create({"service.name": "weaviate-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument Weaviate
WeaviateInstrumentor().instrument()
# 3. Use Weaviate client (ensure a Weaviate instance is running or mocked)
# Replace with your actual Weaviate URL and API key if needed
weaviate_url = os.environ.get("WEAVIATE_URL", "http://localhost:8080")
weaviate_api_key = os.environ.get("WEAVIATE_API_KEY", "YOUR_API_KEY_HERE")
try:
client = weaviate.Client(
url=weaviate_url
# For Weaviate Cloud Services (WCS), uncomment and provide API key:
# auth_client_secret=weaviate.AuthApiKey(api_key=weaviate_api_key)
)
if client.is_connected():
print("Successfully connected to Weaviate. Spans will be generated for operations.")
# Example: Perform a simple query (uncomment and adapt to your schema)
# collection = client.collections.get("YourCollectionName")
# response = collection.query.fetch_objects(limit=1)
# print(f"Query executed. Response: {response}")
else:
print(f"Could not connect to Weaviate at {weaviate_url}. "
"Please ensure Weaviate is running and accessible.")
except Exception as e:
print(f"Error connecting to Weaviate or during operation: {e}")
print("Please ensure your Weaviate instance is running and accessible.")
# Optional: Flush spans to ensure they are exported before program exit
provider.force_flush()
Debug
Known issues
gotchaFrequent updates to OpenTelemetry GenAI semantic conventions (v0.5.0 and later) in `openllmetry` may alter span attribute names and structure. If your consuming system (e.g., an LLM observability platform) relies on specific attribute paths, monitor these changes carefully when upgrading.fixReview the release notes for `openllmetry` and the `opentelemetry-instrumentation-weaviate` package for details on semantic convention changes. Update your data processing or alerting configurations as needed.
affects: >=0.53.0
gotchaThe instrumentation requires `weaviate-client >=3.18.0`. Using older versions of the Weaviate client library may result in incomplete or incorrect instrumentation, or compatibility errors.fixEnsure `weaviate-client` is updated to version 3.18.0 or newer. You can specify this in your `requirements.txt` or `pyproject.toml`.
affects: <3.18.0 (weaviate-client)
gotchaThis instrumentation requires explicit invocation of `WeaviateInstrumentor().instrument()` after setting up a global OpenTelemetry `TracerProvider`. It is not automatically enabled by `opentelemetry-bootstrap` or similar generic auto-instrumentation tools without a custom plugin configuration.fixAlways include `WeaviateInstrumentor().instrument()` in your application startup code, following the setup of your OpenTelemetry `TracerProvider`.
affects: All
Upgrade
Version history
0.62.3latest on PyPI · released Aug 10, 2026
Audit
Dependencies
weaviate-clientrequiredRequired peer dependency for Weaviate interactions. The instrumentation targets this client library.
opentelemetry-sdkrequiredProvides core OpenTelemetry tracing components like TracerProvider and Exporter.