0
# Context Management
1

2
Context management utilities for tracking important application metadata such as sessions, users, metadata, tags, and prompt templates using Python context managers. These utilities integrate with OpenTelemetry context to ensure metadata is automatically attached to all spans created within their scope.
3

4
## Capabilities
5

6
### Session Tracking
7

8
Track multi-turn conversations and group related operations by session.
9

10
```python { .api }
11
class using_session:
12
    """
13
    Context manager to add session ID to the current OpenTelemetry Context.
14
    
15
    Args:
16
        session_id (str): The session identifier to track
17
    """
18
    def __init__(self, session_id: str) -> None: ...
19
    def __enter__(self) -> Self: ...
20
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
21
    async def __aenter__(self) -> Self: ...
22
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...
23
```
24

25
**Usage Example:**
26

27
```python
28
from openinference.instrumentation import using_session
29

30
with using_session("conversation-abc-123"):
31
    # All spans created here will have session.id = "conversation-abc-123"
32
    response = llm_client.chat.completions.create(...)
33
    
34
# Can also be used as a decorator
35
@using_session("batch-process-456")
36
def process_batch():
37
    # All spans in this function will have the session ID
38
    pass
39
```
40

41
### User Tracking
42

43
Track different conversations and operations by user.
44

45
```python { .api }
46
class using_user:
47
    """
48
    Context manager to add user ID to the current OpenTelemetry Context.
49
    
50
    Args:
51
        user_id (str): The user identifier to track
52
    """
53
    def __init__(self, user_id: str) -> None: ...
54
    def __enter__(self) -> Self: ...
55
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
56
    async def __aenter__(self) -> Self: ...
57
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...
58
```
59

60
**Usage Example:**
61

62
```python
63
from openinference.instrumentation import using_user
64

65
with using_user("user-789"):
66
    # All spans created here will have user.id = "user-789"
67
    personalized_response = generate_response(user_preferences)
68
```
69

70
### Metadata Tracking
71

72
Add custom metadata to provide additional context for operations.
73

74
```python { .api }
75
class using_metadata:
76
    """
77
    Context manager to add metadata to the current OpenTelemetry Context.
78
    
79
    Args:
80
        metadata (Dict[str, Any]): Dictionary of metadata key-value pairs
81
    """
82
    def __init__(self, metadata: Dict[str, Any]) -> None: ...
83
    def __enter__(self) -> Self: ...
84
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
85
    async def __aenter__(self) -> Self: ...
86
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...
87
```
88

89
**Usage Example:**
90

91
```python
92
from openinference.instrumentation import using_metadata
93

94
metadata = {
95
    "user_tier": "premium",
96
    "region": "us-west-2",
97
    "feature_flags": {"new_ui": True, "beta_model": False}
98
}
99

100
with using_metadata(metadata):
101
    # All spans will have metadata JSON-serialized and attached
102
    result = complex_operation()
103
```
104

105
### Tag Tracking
106

107
Add tags for filtering and categorization.
108

109
```python { .api }
110
class using_tags:
111
    """
112
    Context manager to add tags to the current OpenTelemetry Context.
113
    
114
    Args:
115
        tags (List[str]): List of string tags
116
    """
117
    def __init__(self, tags: List[str]) -> None: ...
118
    def __enter__(self) -> Self: ...
119
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
120
    async def __aenter__(self) -> Self: ...
121
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...
122
```
123

124
**Usage Example:**
125

126
```python
127
from openinference.instrumentation import using_tags
128

129
tags = ["production", "critical", "customer-facing"]
130

131
with using_tags(tags):
132
    # All spans will have tag.tags = ["production", "critical", "customer-facing"]
133
    critical_operation()
134
```
135

136
### Prompt Template Tracking
137

138
Track prompt templates with their versions and variables for prompt management.
139

140
```python { .api }
141
class using_prompt_template:
142
    """
143
    Context manager to add prompt template information to the current OpenTelemetry Context.
144
    
145
    Args:
146
        template (str): The prompt template string
147
        version (str): Version identifier for the template
148
        variables (Optional[Dict[str, Any]]): Variables used in the template
149
    """
150
    def __init__(
151
        self,
152
        *,
153
        template: str = "",
154
        version: str = "",
155
        variables: Optional[Dict[str, Any]] = None,
156
    ) -> None: ...
157
    def __enter__(self) -> Self: ...
158
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
159
    async def __aenter__(self) -> Self: ...
160
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...
161
```
162

163
**Usage Example:**
164

165
```python
166
from openinference.instrumentation import using_prompt_template
167

168
template = "Generate a {style} summary of the following text: {text}"
169
variables = {"style": "concise", "text": user_input}
170

171
with using_prompt_template(
172
    template=template,
173
    version="v2.1",
174
    variables=variables
175
):
176
    # Spans will include prompt template metadata
177
    summary = llm.generate(prompt)
178
```
179

180
### Combined Attributes
181

182
Convenient context manager for using multiple attribute types together.
183

184
```python { .api }
185
class using_attributes:
186
    """
187
    Context manager to add multiple attributes to the current OpenTelemetry Context.
188
    Combines functionality of other context managers for convenience.
189
    
190
    Args:
191
        session_id (str): Session identifier
192
        user_id (str): User identifier  
193
        metadata (Optional[Dict[str, Any]]): Custom metadata
194
        tags (Optional[List[str]]): List of tags
195
        prompt_template (str): Prompt template string
196
        prompt_template_version (str): Template version
197
        prompt_template_variables (Optional[Dict[str, Any]]): Template variables
198
    """
199
    def __init__(
200
        self,
201
        *,
202
        session_id: str = "",
203
        user_id: str = "",
204
        metadata: Optional[Dict[str, Any]] = None,
205
        tags: Optional[List[str]] = None,
206
        prompt_template: str = "",
207
        prompt_template_version: str = "",
208
        prompt_template_variables: Optional[Dict[str, Any]] = None,
209
    ) -> None: ...
210
    def __enter__(self) -> Self: ...
211
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
212
    async def __aenter__(self) -> Self: ...
213
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...
214
```
215

216
**Usage Example:**
217

218
```python
219
from openinference.instrumentation import using_attributes
220

221
with using_attributes(
222
    session_id="chat-session-123",
223
    user_id="user-456", 
224
    metadata={"tier": "premium", "region": "us-east"},
225
    tags=["chatbot", "support"],
226
    prompt_template="Answer this question: {question}",
227
    prompt_template_version="v1.0",
228
    prompt_template_variables={"question": user_question}
229
):
230
    # All context attributes are applied at once
231
    response = chatbot.respond(user_question)
232
```
233

234
### Context Attribute Extraction
235

236
Extract attributes from the current OpenTelemetry context.
237

238
```python { .api }
239
def get_attributes_from_context() -> Iterator[Tuple[str, AttributeValue]]:
240
    """
241
    Extracts all OpenInference attributes from the current OpenTelemetry context.
242
    
243
    Returns:
244
        Iterator[Tuple[str, AttributeValue]]: Yields (attribute_name, attribute_value) pairs
245
    """
246
```
247

248
**Usage Example:**
249

250
```python
251
from openinference.instrumentation import get_attributes_from_context, using_session
252

253
with using_session("test-session"):
254
    # Get all current context attributes
255
    for attr_name, attr_value in get_attributes_from_context():
256
        print(f"{attr_name}: {attr_value}")
257
    # Output: session.id: test-session
258
```
259

260
## Context Manager Features
261

262
All context managers support:
263

264
- **Synchronous usage**: `with using_session("id"):`
265
- **Asynchronous usage**: `async with using_session("id"):`  
266
- **Decorator usage**: `@using_session("id")`
267
- **Nested usage**: Context managers can be nested or combined
268
- **Exception safety**: Contexts are properly cleaned up even if exceptions occur
269

270
## Attribute Mapping
271

272
The context managers map to the following OpenInference span attributes:
273

274
- `using_session` → `session.id`
275
- `using_user` → `user.id`
276
- `using_metadata` → `metadata` (JSON-serialized)
277
- `using_tags` → `tag.tags` (list)
278
- `using_prompt_template` → `llm.prompt_template.*` attributes