{"id":2651,"library":"opentelemetry-instrumentation-weaviate","title":"OpenTelemetry Weaviate Instrumentation","description":"The `opentelemetry-instrumentation-weaviate` library provides OpenTelemetry tracing capabilities for interactions with Weaviate vector databases. It automatically captures spans for Weaviate client operations, allowing observability into your LLM and RAG pipelines. It is part of the broader OpenLLMetry project, currently at version 0.58.0, and receives frequent updates, especially concerning OpenTelemetry GenAI semantic conventions.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-weaviate","tags":["opentelemetry","instrumentation","weaviate","LLM","RAG","tracing","observability","vector-database"],"install":[{"cmd":"pip install opentelemetry-instrumentation-weaviate weaviate-client opentelemetry-sdk","lang":"bash","label":"Install with Weaviate client and OTel SDK"}],"dependencies":[{"reason":"Required peer dependency for Weaviate interactions. The instrumentation targets this client library.","package":"weaviate-client","optional":false},{"reason":"Provides core OpenTelemetry tracing components like TracerProvider and Exporter.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"WeaviateInstrumentor","correct":"from opentelemetry.instrumentation.weaviate import WeaviateInstrumentor"}],"quickstart":{"code":"import os\nimport weaviate\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.weaviate import WeaviateInstrumentor\n\n# 1. Setup OpenTelemetry TracerProvider and Exporter\nresource = Resource.create({\"service.name\": \"weaviate-app\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Weaviate\nWeaviateInstrumentor().instrument()\n\n# 3. Use Weaviate client (ensure a Weaviate instance is running or mocked)\n# Replace with your actual Weaviate URL and API key if needed\nweaviate_url = os.environ.get(\"WEAVIATE_URL\", \"http://localhost:8080\")\nweaviate_api_key = os.environ.get(\"WEAVIATE_API_KEY\", \"YOUR_API_KEY_HERE\")\n\ntry:\n    client = weaviate.Client(\n        url=weaviate_url\n        # For Weaviate Cloud Services (WCS), uncomment and provide API key:\n        # auth_client_secret=weaviate.AuthApiKey(api_key=weaviate_api_key)\n    )\n\n    if client.is_connected():\n        print(\"Successfully connected to Weaviate. Spans will be generated for operations.\")\n        # Example: Perform a simple query (uncomment and adapt to your schema)\n        # collection = client.collections.get(\"YourCollectionName\")\n        # response = collection.query.fetch_objects(limit=1)\n        # print(f\"Query executed. Response: {response}\")\n    else:\n        print(f\"Could not connect to Weaviate at {weaviate_url}. \"\n              \"Please ensure Weaviate is running and accessible.\")\nexcept Exception as e:\n    print(f\"Error connecting to Weaviate or during operation: {e}\")\n    print(\"Please ensure your Weaviate instance is running and accessible.\")\n\n# Optional: Flush spans to ensure they are exported before program exit\nprovider.force_flush()","lang":"python","description":"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."},"warnings":[{"fix":"Review 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.","message":"Frequent 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.","severity":"gotcha","affected_versions":">=0.53.0"},{"fix":"Ensure `weaviate-client` is updated to version 3.18.0 or newer. You can specify this in your `requirements.txt` or `pyproject.toml`.","message":"The 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.","severity":"gotcha","affected_versions":"<3.18.0 (weaviate-client)"},{"fix":"Always include `WeaviateInstrumentor().instrument()` in your application startup code, following the setup of your OpenTelemetry `TracerProvider`.","message":"This 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}