OpenTelemetry Qdrant Instrumentation

OpenTelemetry instrumentation for the Qdrant vector database client library, enabling automatic tracing and observability for client-side operations against Qdrant vector databases. This library instruments both synchronous and asynchronous Qdrant client methods to capture telemetry data including database operations, query performance metrics, and error tracking.

Package Information

• Package Name: opentelemetry-instrumentation-qdrant
• Package Type: PyPI
• Language: Python
• Installation: pip install opentelemetry-instrumentation-qdrant
• Requires: Python ≥3.9, qdrant-client ≥1.7

Core Imports

from opentelemetry.instrumentation.qdrant import QdrantInstrumentor

For type annotations:

from typing import Collection, Any, Optional, Callable
from opentelemetry.instrumentation.instrumentor import BaseInstrumentor

Basic Usage

from opentelemetry.instrumentation.qdrant import QdrantInstrumentor

# Enable instrumentation
QdrantInstrumentor().instrument()

# Now all Qdrant client operations will be automatically traced
import qdrant_client

client = qdrant_client.QdrantClient("localhost", port=6333)
# Operations like search, upsert, etc. will now generate traces

Capabilities

Instrumentor Class

Main class for enabling and disabling Qdrant client instrumentation.

class QdrantInstrumentor(BaseInstrumentor):
    def __init__(self, exception_logger: Optional[Callable[[Exception], None]] = None):
        """
        Initialize the Qdrant instrumentor.
        
        Args:
            exception_logger: Optional callable for logging exceptions that occur
                            during instrumentation. Function should accept an Exception
                            parameter.
        """
    
    def instrument(self, **kwargs: Any) -> None:
        """
        Enable instrumentation for Qdrant client operations.
        
        Args:
            **kwargs: Additional instrumentation options including:
                - tracer_provider: OpenTelemetry tracer provider to use
        """
    
    def uninstrument(self, **kwargs: Any) -> None:
        """
        Disable instrumentation for Qdrant client operations.
        
        Args:
            **kwargs: Additional uninstrumentation options
        """
    
    def instrumentation_dependencies(self) -> Collection[str]:
        """
        Get the list of packages that this instrumentor depends on.
        
        Returns:
            Collection[str]: List containing "qdrant-client >= 1.7"
        """

Version Information

Package version constant.

from opentelemetry.instrumentation.qdrant.version import __version__

__version__: str  # Current package version (e.g., "0.46.2")

Automatic Instrumentation

The package supports automatic instrumentation discovery through OpenTelemetry's plugin system:

# The instrumentor can be automatically discovered and applied
# when using opentelemetry-bootstrap or similar auto-instrumentation tools

Instrumented Operations

When instrumentation is enabled, the following Qdrant client operations are automatically traced:

Data Operations

• upsert - Insert or update points in a collection
• add - Add documents to a collection
• upload_points - Upload points to a collection
• upload_records - Upload records to a collection
• upload_collection - Upload an entire collection

Search Operations

• search - Vector similarity search
• search_batch - Batch vector searches
• search_groups - Search with result grouping
• query - Query collection with filters
• query_batch - Batch queries
• discover - Discovery search operations
• discover_batch - Batch discovery searches
• recommend - Recommendation searches
• recommend_batch - Batch recommendations
• recommend_groups - Grouped recommendations
• scroll - Scroll through collection points

Management Operations

• delete - Delete points from collection
• delete_vectors - Delete specific vectors
• delete_payload - Delete point payload data
• set_payload - Set payload for points
• overwrite_payload - Overwrite point payload
• update_vectors - Update vector data
• batch_update_points - Batch point updates

Telemetry Data

The instrumentation automatically captures:

• Span Names: Operation-specific names like "qdrant.search", "qdrant.upsert"
• Span Kind: CLIENT spans for all operations
• Vector Database Vendor: Set to "Qdrant" via SpanAttributes.VECTOR_DB_VENDOR
• Collection Names: Target collection for operations via attributes like:
  • qdrant.{method}.collection_name (e.g., qdrant.search.collection_name)
• Point Counts: Number of points in upload operations via:
  • SpanAttributes.QDRANT_UPSERT_POINTS_COUNT for upsert operations
  • qdrant.{method}.points_count for upload methods (add, upload_points, upload_records, upload_collection)
• Search Limits: Query limits via SpanAttributes.VECTOR_DB_QUERY_TOP_K
• Batch Counts: Number of requests in batch operations via:
  • qdrant.{method}.requests_count (for search_batch, recommend_batch, discover_batch)
• Operation Status: Success/failure status via OpenTelemetry span status

Error Handling

The instrumentation includes robust error handling:

• Exceptions during tracing do not affect the original Qdrant operations
• Failed instrumentation attempts are logged rather than raised
• Custom exception loggers can be provided for debugging

Usage Examples

Basic Instrumentation

from opentelemetry.instrumentation.qdrant import QdrantInstrumentor

# Enable instrumentation
instrumentor = QdrantInstrumentor()
instrumentor.instrument()

# Use Qdrant client normally - all operations will be traced
import qdrant_client
client = qdrant_client.QdrantClient("localhost", port=6333)

With Custom Exception Logging

def my_exception_logger(exception):
    print(f"Instrumentation error: {exception}")

instrumentor = QdrantInstrumentor(exception_logger=my_exception_logger)
instrumentor.instrument()

Disabling Instrumentation

# Disable instrumentation when needed
instrumentor.uninstrument()

With Tracer Provider

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

# Set up custom tracer provider
trace.set_tracer_provider(TracerProvider())

# Use custom tracer provider with instrumentation
instrumentor.instrument(tracer_provider=trace.get_tracer_provider())

Integration

This instrumentation works with:

• Synchronous Qdrant clients: qdrant_client.QdrantClient
• Asynchronous Qdrant clients: qdrant_client.AsyncQdrantClient
• OpenTelemetry SDK: Standard OpenTelemetry tracing pipeline
• Auto-instrumentation: OpenTelemetry bootstrap and discovery mechanisms
• Monitoring Systems: Any OpenTelemetry-compatible observability platform

Dependencies

The package has minimal runtime dependencies:

• qdrant-client >= 1.7 (the client library being instrumented)
• OpenTelemetry core libraries for tracing functionality
• wrapt for method wrapping