0
# OpenTelemetry Qdrant Instrumentation
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: opentelemetry-instrumentation-qdrant
7
- **Package Type**: PyPI
8
- **Language**: Python
9
- **Installation**: `pip install opentelemetry-instrumentation-qdrant`
10
- **Requires**: Python ≥3.9, qdrant-client ≥1.7
11

12
## Core Imports
13

14
```python
15
from opentelemetry.instrumentation.qdrant import QdrantInstrumentor
16
```
17

18
For type annotations:
19

20
```python
21
from typing import Collection, Any, Optional, Callable
22
from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
23
```
24

25
## Basic Usage
26

27
```python
28
from opentelemetry.instrumentation.qdrant import QdrantInstrumentor
29

30
# Enable instrumentation
31
QdrantInstrumentor().instrument()
32

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

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

40
## Capabilities
41

42
### Instrumentor Class
43

44
Main class for enabling and disabling Qdrant client instrumentation.
45

46
```python { .api }
47
class QdrantInstrumentor(BaseInstrumentor):
48
    def __init__(self, exception_logger: Optional[Callable[[Exception], None]] = None):
49
        """
50
        Initialize the Qdrant instrumentor.
51
        
52
        Args:
53
            exception_logger: Optional callable for logging exceptions that occur
54
                            during instrumentation. Function should accept an Exception
55
                            parameter.
56
        """
57
    
58
    def instrument(self, **kwargs: Any) -> None:
59
        """
60
        Enable instrumentation for Qdrant client operations.
61
        
62
        Args:
63
            **kwargs: Additional instrumentation options including:
64
                - tracer_provider: OpenTelemetry tracer provider to use
65
        """
66
    
67
    def uninstrument(self, **kwargs: Any) -> None:
68
        """
69
        Disable instrumentation for Qdrant client operations.
70
        
71
        Args:
72
            **kwargs: Additional uninstrumentation options
73
        """
74
    
75
    def instrumentation_dependencies(self) -> Collection[str]:
76
        """
77
        Get the list of packages that this instrumentor depends on.
78
        
79
        Returns:
80
            Collection[str]: List containing "qdrant-client >= 1.7"
81
        """
82
```
83

84
### Version Information
85

86
Package version constant.
87

88
```python { .api }
89
from opentelemetry.instrumentation.qdrant.version import __version__
90

91
__version__: str  # Current package version (e.g., "0.46.2")
92
```
93

94

95
## Automatic Instrumentation
96

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

99
```python
100
# The instrumentor can be automatically discovered and applied
101
# when using opentelemetry-bootstrap or similar auto-instrumentation tools
102
```
103

104
## Instrumented Operations
105

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

108
### Data Operations
109
- `upsert` - Insert or update points in a collection
110
- `add` - Add documents to a collection
111
- `upload_points` - Upload points to a collection
112
- `upload_records` - Upload records to a collection
113
- `upload_collection` - Upload an entire collection
114

115
### Search Operations
116
- `search` - Vector similarity search
117
- `search_batch` - Batch vector searches
118
- `search_groups` - Search with result grouping
119
- `query` - Query collection with filters
120
- `query_batch` - Batch queries
121
- `discover` - Discovery search operations
122
- `discover_batch` - Batch discovery searches
123
- `recommend` - Recommendation searches
124
- `recommend_batch` - Batch recommendations
125
- `recommend_groups` - Grouped recommendations
126
- `scroll` - Scroll through collection points
127

128
### Management Operations
129
- `delete` - Delete points from collection
130
- `delete_vectors` - Delete specific vectors
131
- `delete_payload` - Delete point payload data
132
- `set_payload` - Set payload for points
133
- `overwrite_payload` - Overwrite point payload
134
- `update_vectors` - Update vector data
135
- `batch_update_points` - Batch point updates
136

137
## Telemetry Data
138

139
The instrumentation automatically captures:
140

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

154
## Error Handling
155

156
The instrumentation includes robust error handling:
157

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

162
## Usage Examples
163

164
### Basic Instrumentation
165

166
```python
167
from opentelemetry.instrumentation.qdrant import QdrantInstrumentor
168

169
# Enable instrumentation
170
instrumentor = QdrantInstrumentor()
171
instrumentor.instrument()
172

173
# Use Qdrant client normally - all operations will be traced
174
import qdrant_client
175
client = qdrant_client.QdrantClient("localhost", port=6333)
176
```  
177

178
### With Custom Exception Logging
179

180
```python
181
def my_exception_logger(exception):
182
    print(f"Instrumentation error: {exception}")
183

184
instrumentor = QdrantInstrumentor(exception_logger=my_exception_logger)
185
instrumentor.instrument()
186
```
187

188
### Disabling Instrumentation
189

190
```python
191
# Disable instrumentation when needed
192
instrumentor.uninstrument()
193
```
194

195
### With Tracer Provider
196

197
```python
198
from opentelemetry import trace
199
from opentelemetry.sdk.trace import TracerProvider
200

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

204
# Use custom tracer provider with instrumentation
205
instrumentor.instrument(tracer_provider=trace.get_tracer_provider())
206
```
207

208
## Integration
209

210
This instrumentation works with:
211

212
- **Synchronous Qdrant clients**: `qdrant_client.QdrantClient`
213
- **Asynchronous Qdrant clients**: `qdrant_client.AsyncQdrantClient`
214
- **OpenTelemetry SDK**: Standard OpenTelemetry tracing pipeline
215
- **Auto-instrumentation**: OpenTelemetry bootstrap and discovery mechanisms
216
- **Monitoring Systems**: Any OpenTelemetry-compatible observability platform
217

218
## Dependencies
219

220
The package has minimal runtime dependencies:
221

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