0
# Attribute Generation
1

2
Comprehensive set of functions for generating OpenInference-compliant span attributes for different types of operations including LLM interactions, embeddings, retrievals, and general input/output handling.
3

4
## Capabilities
5

6
### LLM Attributes
7

8
Generate comprehensive attributes for Large Language Model interactions.
9

10
```python { .api }
11
def get_llm_attributes(
12
    *,
13
    provider: Optional[OpenInferenceLLMProvider] = None,
14
    system: Optional[OpenInferenceLLMSystem] = None,
15
    model_name: Optional[str] = None,
16
    invocation_parameters: Optional[Union[str, Dict[str, Any]]] = None,
17
    input_messages: Optional[Sequence[Message]] = None,
18
    output_messages: Optional[Sequence[Message]] = None,
19
    token_count: Optional[TokenCount] = None,
20
    tools: Optional[Sequence[Tool]] = None,
21
) -> Dict[str, AttributeValue]:
22
    """
23
    Generate LLM-related span attributes.
24
    
25
    Args:
26
        provider: LLM provider (e.g., "openai", "anthropic")
27
        system: LLM system (e.g., "openai", "claude")
28
        model_name: Model identifier (e.g., "gpt-4", "claude-3")
29
        invocation_parameters: Model parameters (temperature, max_tokens, etc.)
30
        input_messages: Input messages to the LLM
31
        output_messages: Output messages from the LLM
32
        token_count: Token usage information
33
        tools: Available tools for the LLM
34
        
35
    Returns:
36
        Dict[str, AttributeValue]: OpenInference-compliant attributes
37
    """
38
```
39

40
**Usage Example:**
41

42
```python
43
from openinference.instrumentation import get_llm_attributes
44

45
# Complete LLM interaction attributes
46
attributes = get_llm_attributes(
47
    provider="openai",
48
    model_name="gpt-4",
49
    invocation_parameters={"temperature": 0.7, "max_tokens": 150},
50
    input_messages=[{"role": "user", "content": "Hello!"}],
51
    output_messages=[{"role": "assistant", "content": "Hi there!"}],
52
    token_count={"prompt": 10, "completion": 15, "total": 25}
53
)
54

55
span.set_attributes(attributes)
56
```
57

58
### LLM Component Attributes
59

60
Individual functions for specific LLM attribute components.
61

62
```python { .api }
63
def get_llm_provider_attributes(
64
    provider: Optional[OpenInferenceLLMProvider],
65
) -> Mapping[str, AttributeValue]:
66
    """Generate LLM provider attributes."""
67

68
def get_llm_system_attributes(
69
    system: Optional[OpenInferenceLLMSystem],
70
) -> Mapping[str, AttributeValue]:
71
    """Generate LLM system attributes."""
72

73
def get_llm_model_name_attributes(
74
    model_name: Optional[str],
75
) -> Mapping[str, AttributeValue]:
76
    """Generate LLM model name attributes."""
77

78
def get_llm_invocation_parameter_attributes(
79
    invocation_parameters: Optional[Union[str, Dict[str, Any]]],
80
) -> Mapping[str, AttributeValue]:
81
    """Generate LLM invocation parameter attributes."""
82

83
def get_llm_input_message_attributes(
84
    messages: Optional[Sequence[Message]],
85
) -> Mapping[str, AttributeValue]:
86
    """Generate LLM input message attributes."""
87

88
def get_llm_output_message_attributes(
89
    messages: Optional[Sequence[Message]],
90
) -> Mapping[str, AttributeValue]:
91
    """Generate LLM output message attributes."""
92

93
def get_llm_token_count_attributes(
94
    token_count: Optional[TokenCount],
95
) -> Mapping[str, AttributeValue]:
96
    """Generate LLM token count attributes."""
97

98
def get_llm_tool_attributes(
99
    tools: Optional[Sequence[Tool]],
100
) -> Mapping[str, AttributeValue]:
101
    """Generate LLM tool attributes."""
102
```
103

104
**Usage Example:**
105

106
```python
107
# Generate specific attribute groups
108
provider_attrs = get_llm_provider_attributes("openai")
109
model_attrs = get_llm_model_name_attributes("gpt-4")
110
token_attrs = get_llm_token_count_attributes({"total": 100})
111

112
# Combine as needed
113
combined = {**provider_attrs, **model_attrs, **token_attrs}
114
```
115

116
### Input/Output Attributes
117

118
Generate attributes for general input and output values.
119

120
```python { .api }
121
def get_input_attributes(
122
    value: Any,
123
    *,
124
    mime_type: Optional[OpenInferenceMimeType] = None,
125
) -> Dict[str, AttributeValue]:
126
    """
127
    Generate input-related span attributes.
128
    
129
    Args:
130
        value: Input value (automatically serialized based on type)
131
        mime_type: MIME type override ("text/plain" or "application/json")
132
        
133
    Returns:
134
        Dict[str, AttributeValue]: Input attributes including value and MIME type
135
    """
136

137
def get_output_attributes(
138
    value: Any,
139
    *,
140
    mime_type: Optional[OpenInferenceMimeType] = None,
141
) -> Dict[str, AttributeValue]:
142
    """
143
    Generate output-related span attributes.
144
    
145
    Args:
146
        value: Output value (automatically serialized based on type)
147
        mime_type: MIME type override ("text/plain" or "application/json")
148
        
149
    Returns:
150
        Dict[str, AttributeValue]: Output attributes including value and MIME type
151
    """
152
```
153

154
**Usage Example:**
155

156
```python
157
# Simple values
158
input_attrs = get_input_attributes("Hello, world!")
159
# Results in: {"input.value": "Hello, world!", "input.mime_type": "text/plain"}
160

161
# Complex data
162
output_data = {"result": [1, 2, 3], "status": "success"}
163
output_attrs = get_output_attributes(output_data)
164
# Results in: {"output.value": '{"result": [1, 2, 3], "status": "success"}', "output.mime_type": "application/json"}
165

166
# Custom MIME type
167
json_attrs = get_input_attributes('{"key": "value"}', mime_type="application/json")
168
```
169

170
### Embedding Attributes
171

172
Generate attributes for embedding operations.
173

174
```python { .api }
175
def get_embedding_attributes(
176
    *,
177
    model_name: Optional[str] = None,
178
    embeddings: Optional[List[Embedding]] = None,
179
) -> Dict[str, AttributeValue]:
180
    """
181
    Generate embedding-related span attributes.
182
    
183
    Args:
184
        model_name: Embedding model name
185
        embeddings: List of embeddings with text and vector data
186
        
187
    Returns:
188
        Dict[str, AttributeValue]: Embedding attributes
189
    """
190
```
191

192
**Usage Example:**
193

194
```python
195
embeddings_data = [
196
    {"text": "Hello world", "vector": [0.1, 0.2, 0.3]},
197
    {"text": "Goodbye", "vector": [0.4, 0.5, 0.6]}
198
]
199

200
embedding_attrs = get_embedding_attributes(
201
    model_name="text-embedding-ada-002",
202
    embeddings=embeddings_data
203
)
204
```
205

206
### Retrieval Attributes
207

208
Generate attributes for document retrieval operations.
209

210
```python { .api }
211
def get_retriever_attributes(
212
    *, 
213
    documents: List[Document]
214
) -> Dict[str, AttributeValue]:
215
    """
216
    Generate retriever-related span attributes.
217
    
218
    Args:
219
        documents: Retrieved documents with content, ID, metadata, and scores
220
        
221
    Returns:
222
        Dict[str, AttributeValue]: Retrieval attributes
223
    """
224
```
225

226
**Usage Example:**
227

228
```python
229
retrieved_docs = [
230
    {
231
        "content": "Document content here",
232
        "id": "doc-123",
233
        "metadata": {"source": "database", "timestamp": "2024-01-01"},
234
        "score": 0.95
235
    },
236
    {
237
        "content": "Another document",
238
        "id": "doc-456", 
239
        "score": 0.87
240
    }
241
]
242

243
retrieval_attrs = get_retriever_attributes(documents=retrieved_docs)
244
```
245

246
### Reranker Attributes
247

248
Generate attributes for document reranking operations.
249

250
```python { .api }
251
def get_reranker_attributes(
252
    *,
253
    query: Optional[str] = None,
254
    model_name: Optional[str] = None,
255
    input_documents: Optional[List[Document]] = None,
256
    output_documents: Optional[List[Document]] = None,
257
    top_k: Optional[int] = None,
258
) -> Dict[str, AttributeValue]:
259
    """
260
    Generate reranker-related span attributes.
261
    
262
    Args:
263
        query: Search query used for reranking
264
        model_name: Reranker model name
265
        input_documents: Documents before reranking
266
        output_documents: Documents after reranking
267
        top_k: Number of top documents to return
268
        
269
    Returns:
270
        Dict[str, AttributeValue]: Reranker attributes
271
    """
272
```
273

274
**Usage Example:**
275

276
```python
277
reranker_attrs = get_reranker_attributes(
278
    query="machine learning algorithms",
279
    model_name="cross-encoder/ms-marco-MiniLM-L-6-v2",
280
    input_documents=candidate_docs,
281
    output_documents=reranked_docs,
282
    top_k=5
283
)
284
```
285

286
### Context Attributes
287

288
Generate attributes from context managers.
289

290
```python { .api }
291
def get_context_attributes(
292
    *,
293
    session_id: Optional[str] = None,
294
    user_id: Optional[str] = None,
295
    metadata: Optional[Union[str, Dict[str, Any]]] = None,
296
    tags: Optional[List[str]] = None,
297
) -> Dict[str, AttributeValue]:
298
    """
299
    Generate context-related span attributes.
300
    
301
    Args:
302
        session_id: Session identifier
303
        user_id: User identifier
304
        metadata: Custom metadata (dict or JSON string)
305
        tags: List of tags
306
        
307
    Returns:
308
        Dict[str, AttributeValue]: Context attributes
309
    """
310

311
def get_session_attributes(*, session_id: str) -> Dict[str, AttributeValue]:
312
    """Generate session attributes."""
313

314
def get_user_id_attributes(*, user_id: str) -> Dict[str, AttributeValue]:
315
    """Generate user ID attributes."""
316

317
def get_metadata_attributes(*, metadata: Union[str, Dict[str, Any]]) -> Dict[str, AttributeValue]:
318
    """Generate metadata attributes."""
319

320
def get_tag_attributes(*, tags: List[str]) -> Dict[str, AttributeValue]:
321
    """Generate tag attributes."""
322
```
323

324
**Usage Example:**
325

326
```python
327
# Combined context attributes
328
context_attrs = get_context_attributes(
329
    session_id="session-123",
330
    user_id="user-456",
331
    metadata={"tier": "premium"},
332
    tags=["important", "production"]
333
)
334

335
# Individual attribute types
336
session_attrs = get_session_attributes(session_id="session-abc")
337
user_attrs = get_user_id_attributes(user_id="user-xyz")
338
meta_attrs = get_metadata_attributes(metadata={"key": "value"})
339
tag_attrs = get_tag_attributes(tags=["tag1", "tag2"])
340
```
341

342
### Tool Attributes
343

344
Generate attributes for tool operations.
345

346
```python { .api }
347
def get_tool_attributes(
348
    *,
349
    name: str,
350
    description: Optional[str] = None,
351
    parameters: Union[str, Dict[str, Any]],
352
) -> Dict[str, AttributeValue]:
353
    """
354
    Generate tool attributes.
355
    
356
    Args:
357
        name: Tool name
358
        description: Tool description
359
        parameters: Tool parameters (JSON schema dict or JSON string)
360
        
361
    Returns:
362
        Dict[str, AttributeValue]: Tool attributes
363
    """
364
```
365

366
**Usage Example:**
367

368
```python
369
tool_attrs = get_tool_attributes(
370
    name="calculator",
371
    description="Performs basic arithmetic operations",
372
    parameters={
373
        "type": "object",
374
        "properties": {
375
            "operation": {"type": "string", "enum": ["+", "-", "*", "/"]},
376
            "a": {"type": "number"},
377
            "b": {"type": "number"}
378
        },
379
        "required": ["operation", "a", "b"]
380
    }
381
)
382
```
383

384
### Span Kind Attributes
385

386
Generate span kind attributes for OpenInference span classification.
387

388
```python { .api }
389
def get_span_kind_attributes(kind: OpenInferenceSpanKind) -> Dict[str, AttributeValue]:
390
    """
391
    Generate span kind attributes.
392
    
393
    Args:
394
        kind: OpenInference span kind ("llm", "chain", "agent", "tool", etc.)
395
        
396
    Returns:
397
        Dict[str, AttributeValue]: Span kind attributes
398
    """
399
```
400

401
**Usage Example:**
402

403
```python
404
from openinference.semconv.trace import OpenInferenceSpanKindValues
405

406
# Using enum value
407
llm_kind_attrs = get_span_kind_attributes(OpenInferenceSpanKindValues.LLM)
408

409
# Using string (must be lowercase)
410
chain_kind_attrs = get_span_kind_attributes("chain")
411
```
412

413
## Automatic Serialization
414

415
The attribute generation functions automatically handle serialization:
416

417
- **Strings, numbers, booleans**: Used as-is with `text/plain` MIME type
418
- **Lists, dicts**: JSON-serialized with `application/json` MIME type  
419
- **Dataclasses**: Converted to dict then JSON-serialized
420
- **Pydantic models**: Uses `model_dump()` then JSON-serialized
421
- **Other objects**: Converted to string with `text/plain` MIME type
422

423
## Privacy Integration
424

425
All attribute generation functions integrate with TraceConfig for privacy:
426

427
- Attributes are automatically masked based on configuration
428
- Sensitive data can be redacted or excluded entirely
429
- Image data can be truncated to specified limits
430
- Configuration is applied consistently across all functions