{"id":2165,"library":"opentelemetry-instrumentation-qdrant","title":"OpenTelemetry Qdrant Instrumentation","description":"This library provides automatic OpenTelemetry tracing for the Qdrant vector database client in Python. It's part of the broader OpenLLMetry project, aiming to simplify observability for LLM applications. The library captures Qdrant operations like vector search, upserts, and collection management as OpenTelemetry spans, enriching them with relevant attributes. It typically follows the rapid release cadence of the main OpenLLMetry repository, often with weekly or daily updates.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-qdrant","tags":["opentelemetry","tracing","qdrant","vector database","instrumentation","llm observability","vector search"],"install":[{"cmd":"pip install opentelemetry-instrumentation-qdrant qdrant-client opentelemetry-sdk","lang":"bash","label":"Install with Qdrant client and OTel SDK"}],"dependencies":[{"reason":"Core OpenTelemetry API for tracing.","package":"opentelemetry-api"},{"reason":"Core OpenTelemetry SDK for trace provider and processors.","package":"opentelemetry-sdk"},{"reason":"Used for function wrapping and instrumentation.","package":"wrapt","optional":false},{"reason":"Provides standard semantic conventions for span attributes.","package":"opentelemetry-semantic-conventions","optional":false},{"reason":"Base package for OpenTelemetry instrumentations.","package":"opentelemetry-instrumentation","optional":false},{"reason":"The Qdrant Python client library being instrumented. Users must install this explicitly.","package":"qdrant-client","optional":true}],"imports":[{"symbol":"QdrantInstrumentor","correct":"from opentelemetry.instrumentation.qdrant import QdrantInstrumentor"}],"quickstart":{"code":"import os\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.qdrant import QdrantInstrumentor\nfrom qdrant_client import QdrantClient, models\n\n# 1. Setup OpenTelemetry Tracer Provider and Exporter\nresource = Resource.create({\"service.name\": \"qdrant-example-app\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Qdrant (must be called before client initialization)\nQdrantInstrumentor().instrument()\n\n# 3. Use Qdrant Client (operations will be automatically traced)\n# Using an in-memory client for a self-contained example\nclient = QdrantClient(\":memory:\") # Use \":memory:\" for a local, ephemeral instance\n\ncollection_name = \"my_test_collection\"\nvector_size = 4\n\nprint(f\"Creating collection: {collection_name}\")\nclient.recreate_collection(\n    collection_name=collection_name,\n    vectors_config=models.VectorParams(size=vector_size, distance=models.Distance.COSINE),\n)\n\nprint(\"Upserting points...\")\nclient.upsert(\n    collection_name=collection_name,\n    wait=True,\n    points=[\n        models.PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={\"city\": \"Berlin\"}),\n        models.PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={\"city\": \"London\"})\n    ],\n)\n\nprint(\"Searching points...\")\nsearch_result = client.search(\n    collection_name=collection_name,\n    query_vector=[0.2, 0.7, 0.9, 0.1],\n    limit=1,\n)\nprint(f\"Search result: {search_result}\")\n\n# 4. Ensure traces are flushed (important for ConsoleSpanExporter and script termination)\ntrace.get_tracer_provider().shutdown()\n","lang":"python","description":"This quickstart demonstrates how to set up OpenTelemetry to automatically trace Qdrant client operations. It initializes a basic `TracerProvider` with a `ConsoleSpanExporter`, instruments the Qdrant client, performs a `recreate_collection`, `upsert`, and `search` operation using an in-memory Qdrant client, and then shuts down the tracer provider to ensure all spans are exported."},"warnings":[{"fix":"Review the OpenTelemetry Generative AI Semantic Conventions documentation (https://opentelemetry.io/docs/specs/semconv/ai/llm/) and update your trace analysis queries or dashboards accordingly when upgrading.","message":"Semantic Conventions Updates: `opentelemetry-instrumentation-qdrant` is part of the `openllmetry` project, which frequently updates its instrumentation to conform to the latest OpenTelemetry Generative AI Semantic Conventions. This can lead to changes in span attribute names, types, or structure, requiring updates to trace processing and analysis systems when upgrading `opentelemetry-instrumentation-qdrant` across major semantic convention bumps (e.g., versions from `0.53.0` onwards, aligning with GenAI Semconv `0.5.0` or later).","severity":"breaking","affected_versions":">=0.53.0"},{"fix":"Always ensure you install `qdrant-client` alongside `opentelemetry-instrumentation-qdrant` (e.g., `pip install opentelemetry-instrumentation-qdrant qdrant-client`).","message":"Qdrant Client Installation: This instrumentation package only provides the hooks; it does not install `qdrant-client` itself. Users must explicitly `pip install qdrant-client` in addition to `opentelemetry-instrumentation-qdrant` for the instrumentation to function correctly, as `qdrant-client` is a peer dependency.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `QdrantInstrumentor().instrument()` is called early in your application's startup phase, before any code that initializes or interacts with the `qdrant-client` library.","message":"Instrumentation Order: The `QdrantInstrumentor().instrument()` method must be called *before* any `qdrant_client.QdrantClient` instances are initialized or used. If the `QdrantClient` is created prior to instrumentation, its operations will not be traced.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}