0
# AI Monitoring
1

2
AI-native performance tracking and observability for artificial intelligence workflows, including LLM calls, AI pipeline execution, and token usage monitoring.
3

4
## Capabilities
5

6
### AI Pipeline Tracking
7

8
Track AI workflows and pipelines with automatic exception capture and performance monitoring.
9

10
```python { .api }
11
def ai_track(description: str, **span_kwargs) -> Callable[[F], F]:
12
    """
13
    Decorator for tracking AI operations and pipelines.
14
    
15
    Parameters:
16
    - description: Name/description of the AI operation
17
    - **span_kwargs: Additional span configuration (op, tags, data, etc.)
18
    
19
    Returns:
20
    Decorated function with automatic AI monitoring
21
    """
22
```
23

24
**Usage Examples:**
25

26
```python
27
from sentry_sdk.ai import ai_track
28

29
# Track an AI pipeline
30
@ai_track("user-query-processing")
31
def process_user_query(query, context):
32
    # AI processing logic
33
    response = llm_call(query, context)
34
    return response
35

36
# Track with custom metadata
37
@ai_track(
38
    "document-analysis", 
39
    op="ai.analysis",
40
    sentry_tags={"model": "gpt-4", "type": "document"},
41
    sentry_data={"version": "v2.1"}
42
)
43
async def analyze_document(doc_id):
44
    # Document analysis logic
45
    return results
46
```
47

48
### Pipeline Name Management
49

50
Set and retrieve AI pipeline names for hierarchical tracking and organization.
51

52
```python { .api }
53
def set_ai_pipeline_name(name: Optional[str]) -> None:
54
    """
55
    Set the current AI pipeline name.
56
    
57
    Parameters:
58
    - name: Pipeline name (None to clear)
59
    """
60

61
def get_ai_pipeline_name() -> Optional[str]:
62
    """
63
    Get the current AI pipeline name.
64
    
65
    Returns:
66
    str: Current pipeline name or None if not set
67
    """
68
```
69

70
**Usage Examples:**
71

72
```python
73
from sentry_sdk.ai import set_ai_pipeline_name, get_ai_pipeline_name
74

75
# Set pipeline context manually
76
set_ai_pipeline_name("customer-support-bot")
77

78
# Operations will be tagged with pipeline name
79
process_message(user_input)
80

81
# Check current pipeline
82
current_pipeline = get_ai_pipeline_name()
83
print(f"Running in pipeline: {current_pipeline}")
84
```
85

86
### Token Usage Recording
87

88
Record AI model token consumption for cost tracking and performance analysis.
89

90
```python { .api }
91
def record_token_usage(
92
    span: Span,
93
    input_tokens: Optional[int] = None,
94
    input_tokens_cached: Optional[int] = None,
95
    output_tokens: Optional[int] = None,
96
    output_tokens_reasoning: Optional[int] = None,
97
    total_tokens: Optional[int] = None
98
) -> None:
99
    """
100
    Record token usage metrics for AI operations.
101
    
102
    Parameters:
103
    - span: Active span to attach token data
104
    - input_tokens: Number of input tokens consumed
105
    - input_tokens_cached: Number of cached input tokens
106
    - output_tokens: Number of output tokens generated
107
    - output_tokens_reasoning: Number of reasoning tokens (e.g., o1 models)
108
    - total_tokens: Total tokens (auto-calculated if not provided)
109
    """
110
```
111

112
**Usage Examples:**
113

114
```python
115
import sentry_sdk
116
from sentry_sdk.ai import record_token_usage
117

118
with sentry_sdk.start_span(op="ai.chat.completions", name="openai-completion") as span:
119
    response = openai_client.chat.completions.create(
120
        model="gpt-4",
121
        messages=[{"role": "user", "content": "Hello!"}]
122
    )
123
    
124
    # Record token usage from response
125
    record_token_usage(
126
        span,
127
        input_tokens=response.usage.prompt_tokens,
128
        output_tokens=response.usage.completion_tokens,
129
        total_tokens=response.usage.total_tokens
130
    )
131
```
132

133
### Data Normalization Utilities
134

135
Utilities for normalizing AI model data (e.g., Pydantic models) for Sentry ingestion.
136

137
```python { .api }
138
def set_data_normalized(
139
    span: Span, 
140
    key: str, 
141
    value: Any, 
142
    unpack: bool = True
143
) -> None:
144
    """
145
    Set span data with automatic normalization for complex AI objects.
146
    
147
    Parameters:
148
    - span: Target span for data attachment
149
    - key: Data key name
150
    - value: Value to normalize and attach (supports Pydantic models)
151
    - unpack: Whether to unpack single-item lists
152
    """
153
```
154

155
## Integration Patterns
156

157
### Manual Pipeline Tracking
158

159
```python
160
import sentry_sdk
161
from sentry_sdk.ai import set_ai_pipeline_name, record_token_usage
162

163
# Set pipeline name for all subsequent operations
164
set_ai_pipeline_name("rag-document-qa")
165

166
with sentry_sdk.start_span(op="ai.retrieval", name="vector-search") as span:
167
    documents = vector_db.similarity_search(query)
168
    span.set_data("documents_found", len(documents))
169

170
with sentry_sdk.start_span(op="ai.generation", name="answer-generation") as span:
171
    response = llm.generate(query, documents)
172
    
173
    # Record token usage
174
    record_token_usage(
175
        span,
176
        input_tokens=response.usage.prompt_tokens,
177
        output_tokens=response.usage.completion_tokens
178
    )
179
```
180

181
### Automatic Pipeline Tracking
182

183
```python
184
from sentry_sdk.ai import ai_track
185

186
@ai_track("intelligent-document-processor")
187
def process_documents(files):
188
    results = []
189
    for file in files:
190
        # Each operation is tracked under the pipeline
191
        content = extract_text(file)
192
        summary = summarize_content(content)
193
        insights = analyze_sentiment(content)
194
        results.append({
195
            'summary': summary,
196
            'insights': insights
197
        })
198
    return results
199

200
# Usage - automatically creates pipeline context
201
processed = process_documents(uploaded_files)
202
```
203

204
### Error Tracking in AI Operations
205

206
The `ai_track` decorator automatically captures exceptions with AI-specific context:
207

208
```python
209
@ai_track("model-inference")
210
def run_inference(model_input):
211
    try:
212
        return model.predict(model_input)
213
    except ModelTimeoutError as e:
214
        # Exception automatically captured with AI context
215
        # including pipeline name and operation metadata
216
        raise
217
```
218

219
## AI-Specific Span Data Constants
220

221
The AI monitoring module uses specialized span data constants from `SPANDATA`:
222

223
- `GEN_AI_PIPELINE_NAME` - AI pipeline identifier
224
- `GEN_AI_USAGE_INPUT_TOKENS` - Input token count
225
- `GEN_AI_USAGE_INPUT_TOKENS_CACHED` - Cached input token count
226
- `GEN_AI_USAGE_OUTPUT_TOKENS` - Output token count
227
- `GEN_AI_USAGE_OUTPUT_TOKENS_REASONING` - Reasoning token count
228
- `GEN_AI_USAGE_TOTAL_TOKENS` - Total token consumption
229

230
These constants ensure consistent tagging across AI integrations and custom instrumentation.