0
# OpenInference Instrumentation
1

2
OpenInference Instrumentation is a comprehensive Python library that provides utility functions for OpenInference instrumentation, enabling developers to track important application metadata such as sessions, users, and custom metadata using Python context managers. The library seamlessly integrates with OpenTelemetry ecosystem and supports various auto-instrumentors for different AI/ML frameworks and services.
3

4
## Package Information
5

6
- **Package Name**: openinference-instrumentation
7
- **Language**: Python
8
- **Installation**: `pip install openinference-instrumentation`
9
- **Python Compatibility**: 3.9 - 3.13
10

11
## Core Imports
12

13
```python
14
from openinference.instrumentation import (
15
    using_session, using_user, using_metadata, using_attributes, using_tags, using_prompt_template,
16
    TraceConfig, suppress_tracing, TracerProvider, OITracer, REDACTED_VALUE,
17
    capture_span_context, dangerously_using_project, safe_json_dumps,
18
    get_attributes_from_context
19
)
20
```
21

22
## Basic Usage
23

24
```python
25
from openinference.instrumentation import using_attributes, TraceConfig, suppress_tracing
26

27
# Track a conversation session with metadata
28
metadata = {"user_type": "premium", "region": "us-west"}
29
tags = ["chatbot", "customer_support"]
30

31
with using_attributes(
32
    session_id="session-123",
33
    user_id="user-456", 
34
    metadata=metadata,
35
    tags=tags
36
):
37
    # All spans created within this context will include:
38
    # - session.id = "session-123"
39
    # - user.id = "user-456"  
40
    # - metadata = JSON-serialized metadata
41
    # - tag.tags = ["chatbot", "customer_support"]
42
    your_llm_call()
43

44
# Configure data privacy settings
45
config = TraceConfig(
46
    hide_inputs=True,
47
    hide_llm_invocation_parameters=True
48
)
49

50
# Suppress tracing for sensitive operations
51
with suppress_tracing():
52
    # No tracing will occur within this block
53
    sensitive_operation()
54
```
55

56
## Architecture
57

58
OpenInference Instrumentation is built around several key concepts:
59

60
- **Context Managers**: Python context managers that attach metadata to OpenTelemetry context
61
- **TraceConfig**: Central configuration for controlling tracing behavior and data privacy
62
- **Attribute Generation**: Functions that generate OpenInference-compliant span attributes
63
- **Tracer Integration**: Custom tracer implementation with decorator support for different span kinds
64
- **Type Safety**: Complete TypedDict definitions ensuring type safety across the API
65

66
## Capabilities
67

68
### Context Management
69

70
Python context managers for tracking sessions, users, metadata, tags, and prompt templates. These utilities enable comprehensive span customization in OpenTelemetry-based tracing systems.
71

72
```python { .api }
73
class using_session:
74
    def __init__(self, session_id: str) -> None: ...
75

76
class using_user:
77
    def __init__(self, user_id: str) -> None: ...
78

79
class using_metadata:
80
    def __init__(self, metadata: Dict[str, Any]) -> None: ...
81

82
class using_attributes:
83
    def __init__(
84
        self, 
85
        *, 
86
        session_id: str = "",
87
        user_id: str = "",
88
        metadata: Optional[Dict[str, Any]] = None,
89
        tags: Optional[List[str]] = None,
90
        prompt_template: str = "",
91
        prompt_template_version: str = "",
92
        prompt_template_variables: Optional[Dict[str, Any]] = None
93
    ) -> None: ...
94
```
95

96
[Context Management](./context-management.md)
97

98
### Configuration & Control  
99

100
TraceConfig class for controlling tracing configurations including data privacy settings and payload size limits, plus utilities for suppressing tracing when needed.
101

102
```python { .api }
103
@dataclass(frozen=True)
104
class TraceConfig:
105
    hide_llm_invocation_parameters: Optional[bool] = None
106
    hide_inputs: Optional[bool] = None
107
    hide_outputs: Optional[bool] = None
108
    hide_input_messages: Optional[bool] = None
109
    hide_output_messages: Optional[bool] = None
110
    hide_embedding_vectors: Optional[bool] = None
111
    base64_image_max_length: Optional[int] = None
112
    def mask(self, key: str, value: Union[AttributeValue, Callable[[], AttributeValue]]) -> Optional[AttributeValue]: ...
113

114
class suppress_tracing:
115
    def __enter__(self) -> "suppress_tracing": ...
116
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
117
```
118

119
[Configuration & Control](./configuration.md)
120

121
### Tracer & Spans
122

123
Custom TracerProvider and OITracer implementations with decorator support for creating OpenInference-compliant spans with automatic attribute handling.
124

125
```python { .api }
126
class TracerProvider(OTelTracerProvider):
127
    def __init__(self, *args: Any, config: Optional[TraceConfig] = None, **kwargs: Any) -> None: ...
128
    def get_tracer(self, *args: Any, **kwargs: Any) -> OITracer: ...
129

130
class OITracer:
131
    def start_span(self, name: str, *, openinference_span_kind: Optional[OpenInferenceSpanKind] = None, **kwargs) -> OpenInferenceSpan: ...
132
    def start_as_current_span(self, name: str, *, openinference_span_kind: Optional[OpenInferenceSpanKind] = None, **kwargs) -> Iterator[OpenInferenceSpan]: ...
133
    def agent(self, wrapped_function=None, /, *, name: Optional[str] = None): ...
134
    def chain(self, wrapped_function=None, /, *, name: Optional[str] = None): ...
135
    def tool(self, wrapped_function=None, /, *, name: Optional[str] = None, description: Optional[str] = None, parameters: Optional[Union[str, Dict[str, Any]]] = None): ...
136
    def llm(self, wrapped_function=None, /, *, name: Optional[str] = None, process_input=None, process_output=None): ...
137
```
138

139
[Tracer & Spans](./tracer-spans.md)
140

141
### Attribute Generation
142

143
Comprehensive set of functions for generating OpenInference-compliant span attributes for different types of operations (LLM, embedding, retrieval, etc.).
144

145
```python { .api }
146
def get_llm_attributes(
147
    *,
148
    provider: Optional[OpenInferenceLLMProvider] = None,
149
    model_name: Optional[str] = None,
150
    invocation_parameters: Optional[Union[str, Dict[str, Any]]] = None,
151
    input_messages: Optional[Sequence[Message]] = None,
152
    output_messages: Optional[Sequence[Message]] = None,
153
    token_count: Optional[TokenCount] = None
154
) -> Dict[str, AttributeValue]: ...
155

156
def get_input_attributes(value: Any, *, mime_type: Optional[OpenInferenceMimeType] = None) -> Dict[str, AttributeValue]: ...
157

158
def get_output_attributes(value: Any, *, mime_type: Optional[OpenInferenceMimeType] = None) -> Dict[str, AttributeValue]: ...
159
```
160

161
[Attribute Generation](./attribute-generation.md)
162

163
### Type Definitions
164

165
Complete TypedDict definitions for all data structures used in OpenInference tracing, ensuring type safety and proper structure validation.
166

167
```python { .api }
168
class Message(TypedDict, total=False):
169
    role: str
170
    content: str
171
    contents: Sequence[MessageContent]
172
    tool_call_id: str
173
    tool_calls: Sequence[ToolCall]
174

175
class TokenCount(TypedDict, total=False):
176
    prompt: int
177
    completion: int
178
    total: int
179
    prompt_details: PromptDetails
180

181
class Document(TypedDict, total=False):
182
    content: str
183
    id: Union[str, int]
184
    metadata: Union[str, Dict[str, Any]]
185
    score: float
186
```
187

188
[Type Definitions](./type-definitions.md)
189

190
### Utilities
191

192
Helper functions and utilities for JSON serialization, span context capture, and project management.
193

194
```python { .api }
195
def safe_json_dumps(obj: Any, **kwargs: Any) -> str: ...
196

197
class capture_span_context:
198
    def __init__(self) -> None: ...
199
    def get_first_span_id(self) -> Optional[str]: ...
200
    def get_last_span_id(self) -> Optional[str]: ...
201
    def get_span_contexts(self) -> Sequence[SpanContext]: ...
202

203
class dangerously_using_project:
204
    def __init__(self, project_name: str) -> None: ...
205
```
206

207
[Utilities](./utilities.md)