0
# OpenTelemetry Cohere Instrumentation
1

2
OpenTelemetry instrumentation package for Cohere AI Python library. Provides automatic tracing and monitoring of Cohere API calls including completion, chat, and rerank operations. Captures detailed telemetry data about LLM requests and responses, including prompts, completions, and embeddings with configurable privacy controls.
3

4
## Package Information
5

6
- **Package Name**: opentelemetry-instrumentation-cohere
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install opentelemetry-instrumentation-cohere`
10

11
## Core Imports
12

13
```python
14
from opentelemetry.instrumentation.cohere import CohereInstrumentor
15
```
16

17
## Basic Usage
18

19
```python
20
from opentelemetry.instrumentation.cohere import CohereInstrumentor
21
import cohere
22

23
# Instrument Cohere calls with default settings
24
CohereInstrumentor().instrument()
25

26
# Create Cohere client (instrumentation applies automatically)
27
client = cohere.Client("your-api-key")
28

29
# All Cohere API calls are now automatically traced
30
response = client.chat(message="Hello, world!")
31
completion = client.generate(prompt="Once upon a time...")
32
rerank_result = client.rerank(
33
    query="What is machine learning?",
34
    documents=["AI overview", "ML tutorial", "Deep learning guide"]
35
)
36
```
37

38
## Architecture
39

40
The instrumentation follows OpenTelemetry's BaseInstrumentor pattern and uses function wrapping to intercept Cohere API calls:
41

42
- **CohereInstrumentor**: Main instrumentor class that manages instrumentation lifecycle
43
- **Span Creation**: Creates spans for each Cohere API call with semantic attributes  
44
- **Event Emission**: Supports both legacy span attributes and modern event-based telemetry
45
- **Privacy Controls**: Configurable content tracing via environment variables
46
- **Error Handling**: Robust error handling with optional custom exception logging
47

48
## Capabilities
49

50
### Instrumentation Management
51

52
Core functionality for enabling and disabling OpenTelemetry instrumentation of Cohere API calls.
53

54
```python { .api }
55
class CohereInstrumentor(BaseInstrumentor):
56
    """An instrumentor for Cohere's client library."""
57
    
58
    def __init__(self, exception_logger=None, use_legacy_attributes=True):
59
        """
60
        Initialize the Cohere instrumentor.
61
        
62
        Parameters:
63
        - exception_logger: Optional custom exception logger function
64
        - use_legacy_attributes: Whether to use legacy span attributes (default: True)
65
        """
66
    
67
    def instrument(self, **kwargs):
68
        """
69
        Enable instrumentation of Cohere API calls.
70
        
71
        Parameters:
72
        - tracer_provider: Optional OpenTelemetry TracerProvider
73
        - event_logger_provider: Optional EventLoggerProvider for non-legacy mode
74
        """
75
    
76
    def uninstrument(self, **kwargs):
77
        """Disable instrumentation and restore original Cohere client methods."""
78
    
79
    def instrumentation_dependencies(self) -> Collection[str]:
80
        """
81
        Return collection of required package dependencies.
82
        
83
        Returns:
84
        Collection[str]: Tuple containing package dependency specifications
85
        """
86
```
87

88
### Configuration Management
89

90
Configuration settings that control instrumentation behavior and privacy options.
91

92
```python { .api }
93
class Config:
94
    """Configuration class for instrumentation settings."""
95
    
96
    exception_logger = None  # Custom exception logger function
97
    use_legacy_attributes: bool = True  # Boolean flag for legacy attributes
98
```
99

100
### Internal Utility Functions
101

102
These functions are available from internal modules but not exported at the package level. They are used internally by the instrumentation.
103

104
```python { .api }
105
# From opentelemetry.instrumentation.cohere.utils
106
def should_send_prompts() -> bool:
107
    """
108
    Determine if prompts should be traced based on TRACELOOP_TRACE_CONTENT environment variable.
109
    
110
    Returns:
111
    bool: True if content should be traced, False otherwise
112
    """
113

114
def should_emit_events() -> bool:
115
    """
116
    Check if instrumentation should emit events instead of using legacy attributes.
117
    
118
    Returns:
119
    bool: True if events should be emitted, False for legacy attributes
120
    """
121

122
def dont_throw(func):
123
    """
124
    Decorator that wraps functions to log exceptions instead of throwing them.
125
    Uses the Config.exception_logger if available for custom exception handling.
126
    
127
    Parameters:
128
    - func: The function to wrap
129
    
130
    Returns:
131
    Wrapper function that logs exceptions instead of raising them
132
    """
133
```
134

135
### Internal Span Attribute Management
136

137
Functions for setting telemetry attributes on OpenTelemetry spans based on Cohere API requests and responses. These are internal functions not typically used directly.
138

139
```python { .api }
140
# From opentelemetry.instrumentation.cohere.span_utils
141
def _set_span_chat_response(span, response):
142
    """
143
    Set span attributes specific to chat responses.
144
    
145
    Parameters:
146
    - span: OpenTelemetry span object
147
    - response: Cohere chat response object
148
    """
149

150
def _set_span_generations_response(span, response):
151
    """
152
    Set span attributes specific to completion generation responses.
153
    
154
    Parameters:
155
    - span: OpenTelemetry span object
156
    - response: Cohere generation response object
157
    """
158

159
def _set_span_rerank_response(span, response):
160
    """
161
    Set span attributes specific to rerank responses.
162
    
163
    Parameters:
164
    - span: OpenTelemetry span object
165
    - response: Cohere rerank response object
166
    """
167

168
def set_input_attributes(span, llm_request_type, kwargs):
169
    """
170
    Set input attributes on span for LLM requests.
171
    
172
    Parameters:
173
    - span: OpenTelemetry span object
174
    - llm_request_type: Type of LLM request (completion, chat, rerank)
175
    - kwargs: Request parameters from Cohere API call
176
    """
177

178
def set_response_attributes(span, llm_request_type, response):
179
    """
180
    Set response attributes on span for LLM responses.
181
    
182
    Parameters:
183
    - span: OpenTelemetry span object
184
    - llm_request_type: Type of LLM request (completion, chat, rerank)
185
    - response: Response object from Cohere API
186
    """
187

188
def set_span_request_attributes(span, kwargs):
189
    """
190
    Set general request attributes on span.
191
    
192
    Parameters:
193
    - span: OpenTelemetry span object
194
    - kwargs: Request parameters including model, temperature, tokens, etc.
195
    """
196

197
def _set_span_attribute(span, name, value):
198
    """
199
    Helper function to safely set span attributes, only if value is not None or empty.
200
    
201
    Parameters:
202
    - span: OpenTelemetry span object
203
    - name: Attribute name
204
    - value: Attribute value
205
    """
206
```
207

208
### Internal Event Emission
209

210
Event-based telemetry functions for modern OpenTelemetry instrumentation (when not using legacy attributes). These are internal functions not typically used directly.
211

212
```python { .api }
213
# From opentelemetry.instrumentation.cohere.event_emitter
214
def _parse_response_event(index: int, llm_request_type: str, response) -> ChoiceEvent:
215
    """
216
    Parse Cohere API response into a ChoiceEvent for event emission.
217
    
218
    Parameters:
219
    - index: Index of the response choice
220
    - llm_request_type: Type of LLM request
221
    - response: Cohere API response object
222
    
223
    Returns:
224
    ChoiceEvent: Structured event object
225
    """
226

227
def _emit_message_event(event: MessageEvent, event_logger: EventLogger) -> None:
228
    """
229
    Emit a message event to OpenTelemetry event logger.
230
    
231
    Parameters:
232
    - event: MessageEvent to emit
233
    - event_logger: OpenTelemetry EventLogger instance
234
    """
235

236
def _emit_choice_event(event: ChoiceEvent, event_logger: EventLogger) -> None:
237
    """
238
    Emit a choice event to OpenTelemetry event logger.
239
    
240
    Parameters:
241
    - event: ChoiceEvent to emit
242
    - event_logger: OpenTelemetry EventLogger instance
243
    """
244

245
def emit_input_event(event_logger, llm_request_type: str, kwargs):
246
    """
247
    Emit input events for LLM requests.
248
    
249
    Parameters:
250
    - event_logger: OpenTelemetry EventLogger instance
251
    - llm_request_type: Type of LLM request
252
    - kwargs: Request parameters
253
    """
254

255
def emit_response_events(event_logger, llm_request_type: str, response):
256
    """
257
    Emit response events for LLM responses.
258
    
259
    Parameters:
260
    - event_logger: OpenTelemetry EventLogger instance
261
    - llm_request_type: Type of LLM request
262
    - response: Response object from Cohere API
263
    """
264

265
def emit_event(event: Union[MessageEvent, ChoiceEvent], event_logger: Union[EventLogger, None]):
266
    """
267
    General event emitter for MessageEvent or ChoiceEvent.
268
    
269
    Parameters:
270
    - event: Event object to emit
271
    - event_logger: OpenTelemetry EventLogger instance
272
    """
273
```
274

275
## Types
276

277
### Event Models
278

279
```python { .api }
280
# From opentelemetry.instrumentation.cohere.event_models
281
@dataclass
282
class MessageEvent:
283
    """Represents an input event for the AI model."""
284
    
285
    content: Any  # Message content
286
    role: str = "user"  # Message role
287
    tool_calls: Optional[List[ToolCall]] = None  # Tool calls
288

289
@dataclass
290
class ChoiceEvent:
291
    """Represents a completion event for the AI model."""
292
    
293
    index: int  # Choice index
294
    message: CompletionMessage  # Completion message
295
    finish_reason: str = "unknown"  # Completion finish reason
296
    tool_calls: Optional[List[ToolCall]] = None  # Tool calls
297

298
class ToolCall(TypedDict):
299
    """Represents a tool call in the AI model."""
300
    
301
    id: str  # Tool call ID
302
    function: _FunctionToolCall  # Function call details
303
    type: Literal["function"]  # Tool call type
304

305
class CompletionMessage(TypedDict):
306
    """Represents a message in the AI model."""
307
    
308
    content: Any  # Message content
309
    role: str = "assistant"  # Message role
310

311
class _FunctionToolCall(TypedDict):
312
    function_name: str  # Function name
313
    arguments: Optional[dict[str, Any]]  # Function arguments
314
```
315

316
## Constants
317

318
### Supported Operations
319

320
```python { .api }
321
WRAPPED_METHODS = [
322
    {
323
        "object": "Client",
324
        "method": "generate", 
325
        "span_name": "cohere.completion",
326
    },
327
    {
328
        "object": "Client",
329
        "method": "chat",
330
        "span_name": "cohere.chat", 
331
    },
332
    {
333
        "object": "Client",
334
        "method": "rerank",
335
        "span_name": "cohere.rerank",
336
    },
337
]
338
```
339

340
### Package Dependencies
341

342
```python { .api }
343
_instruments = ("cohere >=4.2.7, <6",)
344
```
345

346
### Semantic Convention Constants
347

348
```python { .api }
349
# Request type values for different Cohere operations
350
LLMRequestTypeValues.CHAT = "llm.chat"
351
LLMRequestTypeValues.COMPLETION = "llm.completion" 
352
LLMRequestTypeValues.RERANK = "llm.rerank"
353
LLMRequestTypeValues.UNKNOWN = "llm.unknown"
354
```
355

356
### Environment Variables
357

358
```python { .api }
359
TRACELOOP_TRACE_CONTENT = "TRACELOOP_TRACE_CONTENT"
360
```
361

362
### Internal Event Constants
363

364
```python { .api }
365
# From opentelemetry.instrumentation.cohere.event_emitter
366
EVENT_ATTRIBUTES = {
367
    "gen_ai.system": "cohere"
368
}
369

370
VALID_MESSAGE_ROLES = {"user", "assistant", "system", "tool"}
371

372
class Roles(Enum):
373
    USER = "user"
374
    ASSISTANT = "assistant" 
375
    SYSTEM = "system"
376
    TOOL = "tool"
377
```
378

379
### Internal Wrapper Functions
380

381
```python { .api }
382
# From opentelemetry.instrumentation.cohere.__init__
383
def _with_tracer_wrapper(func):
384
    """
385
    Helper decorator for providing tracer context to wrapper functions.
386
    
387
    Parameters:
388
    - func: Function to wrap with tracer context
389
    
390
    Returns:
391
    Decorated function with tracer context
392
    """
393

394
def _llm_request_type_by_method(method_name: str):
395
    """
396
    Map Cohere client method names to LLM request type values.
397
    
398
    Parameters:
399
    - method_name: Name of the Cohere client method
400
    
401
    Returns:
402
    LLMRequestTypeValues: Corresponding request type enum value
403
    """
404

405
def _wrap(tracer, event_logger, to_wrap, wrapped, instance, args, kwargs):
406
    """
407
    Core wrapper function that instruments Cohere API calls with OpenTelemetry spans.
408
    
409
    Parameters:
410
    - tracer: OpenTelemetry Tracer instance
411
    - event_logger: EventLogger for modern telemetry mode
412
    - to_wrap: Method configuration from WRAPPED_METHODS
413
    - wrapped: Original method being wrapped
414
    - instance: Instance of the Cohere client
415
    - args: Method arguments
416
    - kwargs: Method keyword arguments
417
    
418
    Returns:
419
    Result from the original Cohere API call
420
    """
421
```
422

423
## Environment Configuration
424

425
### Privacy Control
426

427
By default, this instrumentation logs prompts, completions, and embeddings to span attributes for visibility and debugging. To disable content logging for privacy or trace size reduction:
428

429
```bash
430
export TRACELOOP_TRACE_CONTENT=false
431
```
432

433
Set to `true` (default) to enable content tracing, `false` to disable.
434

435
## Advanced Usage
436

437
### Custom Exception Logging
438

439
```python
440
def custom_exception_logger(exception):
441
    print(f"Instrumentation error: {exception}")
442

443
instrumentor = CohereInstrumentor(exception_logger=custom_exception_logger)
444
instrumentor.instrument()
445
```
446

447
### Event-Based Telemetry
448

449
```python
450
from opentelemetry.sdk._events import EventLoggerProvider
451
from opentelemetry.sdk._logs import LoggerProvider
452

453
# Setup for modern event-based telemetry
454
log_provider = LoggerProvider()
455
event_logger_provider = EventLoggerProvider(log_provider)
456

457
instrumentor = CohereInstrumentor(use_legacy_attributes=False)
458
instrumentor.instrument(event_logger_provider=event_logger_provider)
459
```
460

461
### Instrumentation with Custom Tracer Provider
462

463
```python
464
from opentelemetry.sdk.trace import TracerProvider
465

466
tracer_provider = TracerProvider()
467
instrumentor = CohereInstrumentor()
468
instrumentor.instrument(tracer_provider=tracer_provider)
469
```
470

471
## Supported Cohere Operations
472

473
The instrumentation automatically traces these Cohere client operations:
474

475
1. **Text Completion** (`client.generate`) - Creates spans with name "cohere.completion"
476
2. **Chat Completion** (`client.chat`) - Creates spans with name "cohere.chat"  
477
3. **Document Reranking** (`client.rerank`) - Creates spans with name "cohere.rerank"
478

479
Each operation captures request parameters, response data, token usage, and timing information according to OpenTelemetry semantic conventions.