OpenTelemetry Qdrant Instrumentation

0.58.0 · active · verified Thu Apr 09

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.

Warnings

breaking 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).
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.
gotcha 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.
Fix: Always ensure you install `qdrant-client` alongside `opentelemetry-instrumentation-qdrant` (e.g., `pip install opentelemetry-instrumentation-qdrant qdrant-client`).
gotcha 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.
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.

Install

pip install opentelemetry-instrumentation-qdrant qdrant-client opentelemetry-sdk Install with Qdrant client and OTel SDK

Imports

QdrantInstrumentor

from opentelemetry.instrumentation.qdrant import QdrantInstrumentor

Quickstart

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.

import os
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.qdrant import QdrantInstrumentor
from qdrant_client import QdrantClient, models

# 1. Setup OpenTelemetry Tracer Provider and Exporter
resource = Resource.create({"service.name": "qdrant-example-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 2. Instrument Qdrant (must be called before client initialization)
QdrantInstrumentor().instrument()

# 3. Use Qdrant Client (operations will be automatically traced)
# Using an in-memory client for a self-contained example
client = QdrantClient(":memory:") # Use ":memory:" for a local, ephemeral instance

collection_name = "my_test_collection"
vector_size = 4

print(f"Creating collection: {collection_name}")
client.recreate_collection(
    collection_name=collection_name,
    vectors_config=models.VectorParams(size=vector_size, distance=models.Distance.COSINE),
)

print("Upserting points...")
client.upsert(
    collection_name=collection_name,
    wait=True,
    points=[
        models.PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Berlin"}),
        models.PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={"city": "London"})
    ],
)

print("Searching points...")
search_result = client.search(
    collection_name=collection_name,
    query_vector=[0.2, 0.7, 0.9, 0.1],
    limit=1,
)
print(f"Search result: {search_result}")

# 4. Ensure traces are flushed (important for ConsoleSpanExporter and script termination)
trace.get_tracer_provider().shutdown()

view raw JSON →