Skip to content

Traces

Trace

Bases: ABC

A complete end-to-end workflow containing related spans and metadata.

A trace represents a logical workflow or operation (e.g., "Customer Service Query" or "Code Generation") and contains all the spans (individual operations) that occur during that workflow.

Example 
# Basic trace usage
with trace("Order Processing") as t:
    validation_result = await Runner.run(validator, order_data)
    if validation_result.approved:
        await Runner.run(processor, order_data)

# Trace with metadata and grouping
with trace(
    "Customer Service",
    group_id="chat_123",
    metadata={"customer": "user_456"}
) as t:
    result = await Runner.run(support_agent, query)
Notes
  • Use descriptive workflow names
  • Group related traces with consistent group_ids
  • Add relevant metadata for filtering/analysis
  • Use context managers for reliable cleanup
  • Consider privacy when adding trace data
Source code in src/agents/tracing/traces.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
class Trace(abc.ABC):
    """A complete end-to-end workflow containing related spans and metadata.

    A trace represents a logical workflow or operation (e.g., "Customer Service Query"
    or "Code Generation") and contains all the spans (individual operations) that occur
    during that workflow.

    Example:
        ```python
        # Basic trace usage
        with trace("Order Processing") as t:
            validation_result = await Runner.run(validator, order_data)
            if validation_result.approved:
                await Runner.run(processor, order_data)

        # Trace with metadata and grouping
        with trace(
            "Customer Service",
            group_id="chat_123",
            metadata={"customer": "user_456"}
        ) as t:
            result = await Runner.run(support_agent, query)
        ```

    Notes:
        - Use descriptive workflow names
        - Group related traces with consistent group_ids
        - Add relevant metadata for filtering/analysis
        - Use context managers for reliable cleanup
        - Consider privacy when adding trace data
    """

    @abc.abstractmethod
    def __enter__(self) -> Trace:
        pass

    @abc.abstractmethod
    def __exit__(self, exc_type, exc_val, exc_tb):
        pass

    @abc.abstractmethod
    def start(self, mark_as_current: bool = False):
        """Start the trace and optionally mark it as the current trace.

        Args:
            mark_as_current: If true, marks this trace as the current trace
                in the execution context.

        Notes:
            - Must be called before any spans can be added
            - Only one trace can be current at a time
            - Thread-safe when using mark_as_current
        """
        pass

    @abc.abstractmethod
    def finish(self, reset_current: bool = False):
        """Finish the trace and optionally reset the current trace.

        Args:
            reset_current: If true, resets the current trace to the previous
                trace in the execution context.

        Notes:
            - Must be called to complete the trace
            - Finalizes all open spans
            - Thread-safe when using reset_current
        """
        pass

    @property
    @abc.abstractmethod
    def trace_id(self) -> str:
        """Get the unique identifier for this trace.

        Returns:
            str: The trace's unique ID in the format 'trace_<32_alphanumeric>'

        Notes:
            - IDs are globally unique
            - Used to link spans to their parent trace
            - Can be used to look up traces in the dashboard
        """
        pass

    @property
    @abc.abstractmethod
    def name(self) -> str:
        """Get the human-readable name of this workflow trace.

        Returns:
            str: The workflow name (e.g., "Customer Service", "Data Processing")

        Notes:
            - Should be descriptive and meaningful
            - Used for grouping and filtering in the dashboard
            - Helps identify the purpose of the trace
        """
        pass

    @abc.abstractmethod
    def export(self) -> dict[str, Any] | None:
        """Export the trace data as a serializable dictionary.

        Returns:
            dict | None: Dictionary containing trace data, or None if tracing is disabled.

        Notes:
            - Includes all spans and their data
            - Used for sending traces to backends
            - May include metadata and group ID
        """
        pass

    @property
    @abc.abstractmethod
    def tracing_api_key(self) -> str | None:
        """The API key to use when exporting this trace and its spans."""
        pass

    def to_json(self, *, include_tracing_api_key: bool = False) -> dict[str, Any] | None:
        """Serialize trace metadata for persistence or transport.

        Args:
            include_tracing_api_key: When True, include the tracing API key. Defaults to False
                to avoid persisting secrets unintentionally.
        """
        exported = self.export()
        if exported is None:
            return None
        payload = dict(exported)
        if include_tracing_api_key and self.tracing_api_key:
            payload["tracing_api_key"] = self.tracing_api_key
        return payload

trace_id abstractmethod property 

trace_id: str

Get the unique identifier for this trace.

Returns:

Name Type Description
str str

The trace's unique ID in the format 'trace_<32_alphanumeric>'
Notes
  • IDs are globally unique
  • Used to link spans to their parent trace
  • Can be used to look up traces in the dashboard

name abstractmethod property 

name: str

Get the human-readable name of this workflow trace.

Returns:

Name Type Description
str str

The workflow name (e.g., "Customer Service", "Data Processing")
Notes
  • Should be descriptive and meaningful
  • Used for grouping and filtering in the dashboard
  • Helps identify the purpose of the trace

tracing_api_key abstractmethod property 

tracing_api_key: str | None

The API key to use when exporting this trace and its spans.

start abstractmethod 

start(mark_as_current: bool = False)

Start the trace and optionally mark it as the current trace.

Parameters:

Name Type Description Default
mark_as_current bool

If true, marks this trace as the current trace in the execution context.

 False
Notes
  • Must be called before any spans can be added
  • Only one trace can be current at a time
  • Thread-safe when using mark_as_current
Source code in src/agents/tracing/traces.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
@abc.abstractmethod
def start(self, mark_as_current: bool = False):
    """Start the trace and optionally mark it as the current trace.

    Args:
        mark_as_current: If true, marks this trace as the current trace
            in the execution context.

    Notes:
        - Must be called before any spans can be added
        - Only one trace can be current at a time
        - Thread-safe when using mark_as_current
    """
    pass

finish abstractmethod 

finish(reset_current: bool = False)

Finish the trace and optionally reset the current trace.

Parameters:

Name Type Description Default
reset_current bool

If true, resets the current trace to the previous trace in the execution context.

 False
Notes
  • Must be called to complete the trace
  • Finalizes all open spans
  • Thread-safe when using reset_current
Source code in src/agents/tracing/traces.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@abc.abstractmethod
def finish(self, reset_current: bool = False):
    """Finish the trace and optionally reset the current trace.

    Args:
        reset_current: If true, resets the current trace to the previous
            trace in the execution context.

    Notes:
        - Must be called to complete the trace
        - Finalizes all open spans
        - Thread-safe when using reset_current
    """
    pass

export abstractmethod 

export() -> dict[str, Any] | None

Export the trace data as a serializable dictionary.

Returns:

Type Description
dict[str, Any] | None

dict | None: Dictionary containing trace data, or None if tracing is disabled.
Notes
  • Includes all spans and their data
  • Used for sending traces to backends
  • May include metadata and group ID
Source code in src/agents/tracing/traces.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
@abc.abstractmethod
def export(self) -> dict[str, Any] | None:
    """Export the trace data as a serializable dictionary.

    Returns:
        dict | None: Dictionary containing trace data, or None if tracing is disabled.

    Notes:
        - Includes all spans and their data
        - Used for sending traces to backends
        - May include metadata and group ID
    """
    pass

to_json 

to_json(
    *, include_tracing_api_key: bool = False
) -> dict[str, Any] | None

Serialize trace metadata for persistence or transport.

Parameters:

Name Type Description Default
include_tracing_api_key bool

When True, include the tracing API key. Defaults to False to avoid persisting secrets unintentionally.

 False
Source code in src/agents/tracing/traces.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def to_json(self, *, include_tracing_api_key: bool = False) -> dict[str, Any] | None:
    """Serialize trace metadata for persistence or transport.

    Args:
        include_tracing_api_key: When True, include the tracing API key. Defaults to False
            to avoid persisting secrets unintentionally.
    """
    exported = self.export()
    if exported is None:
        return None
    payload = dict(exported)
    if include_tracing_api_key and self.tracing_api_key:
        payload["tracing_api_key"] = self.tracing_api_key
    return payload

TraceState dataclass

Serializable trace metadata for run state persistence.

Source code in src/agents/tracing/traces.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
@dataclass
class TraceState:
    """Serializable trace metadata for run state persistence."""

    trace_id: str | None = None
    workflow_name: str | None = None
    group_id: str | None = None
    metadata: dict[str, Any] | None = None
    tracing_api_key: str | None = None
    object_type: str | None = None
    extra: dict[str, Any] = field(default_factory=dict)

    @classmethod
    def from_trace(cls, trace: Trace | None) -> TraceState | None:
        if trace is None:
            return None
        payload = trace.to_json(include_tracing_api_key=True)
        return cls.from_json(payload)

    @classmethod
    def from_json(cls, payload: Mapping[str, Any] | None) -> TraceState | None:
        if not payload:
            return None
        data = dict(payload)
        object_type = data.pop("object", None)
        trace_id = data.pop("id", None) or data.pop("trace_id", None)
        workflow_name = data.pop("workflow_name", None)
        group_id = data.pop("group_id", None)
        metadata_value = data.pop("metadata", None)
        metadata = metadata_value if isinstance(metadata_value, dict) else None
        tracing_api_key = data.pop("tracing_api_key", None)
        return cls(
            trace_id=trace_id if isinstance(trace_id, str) else None,
            workflow_name=workflow_name if isinstance(workflow_name, str) else None,
            group_id=group_id if isinstance(group_id, str) else None,
            metadata=metadata,
            tracing_api_key=tracing_api_key if isinstance(tracing_api_key, str) else None,
            object_type=object_type if isinstance(object_type, str) else None,
            extra=data,
        )

    def to_json(self, *, include_tracing_api_key: bool = False) -> dict[str, Any] | None:
        if (
            self.trace_id is None
            and self.workflow_name is None
            and self.group_id is None
            and self.metadata is None
            and self.tracing_api_key is None
            and self.object_type is None
            and not self.extra
        ):
            return None
        payload: dict[str, Any] = {}
        if self.object_type:
            payload["object"] = self.object_type
        if self.trace_id:
            payload["id"] = self.trace_id
        if self.workflow_name is not None:
            payload["workflow_name"] = self.workflow_name
        if self.group_id is not None:
            payload["group_id"] = self.group_id
        if self.metadata is not None:
            payload["metadata"] = dict(self.metadata)
        if include_tracing_api_key and self.tracing_api_key:
            payload["tracing_api_key"] = self.tracing_api_key
        for key, value in self.extra.items():
            if key not in payload:
                payload[key] = value
        return payload

NoOpTrace

Bases: Trace

A no-op implementation of Trace that doesn't record any data.

Used when tracing is disabled but trace operations still need to work. Maintains proper context management but doesn't store or export any data.

Example 
# When tracing is disabled, traces become NoOpTrace
with trace("Disabled Workflow") as t:
    # Operations still work but nothing is recorded
    await Runner.run(agent, "query")
Source code in src/agents/tracing/traces.py 
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
class NoOpTrace(Trace):
    """A no-op implementation of Trace that doesn't record any data.

    Used when tracing is disabled but trace operations still need to work.
    Maintains proper context management but doesn't store or export any data.

    Example:
        ```python
        # When tracing is disabled, traces become NoOpTrace
        with trace("Disabled Workflow") as t:
            # Operations still work but nothing is recorded
            await Runner.run(agent, "query")
        ```
    """

    def __init__(self):
        self._started = False
        self._prev_context_token: contextvars.Token[Trace | None] | None = None

    def __enter__(self) -> Trace:
        if self._started:
            if not self._prev_context_token:
                logger.error("Trace already started but no context token set")
            return self

        self._started = True
        self.start(mark_as_current=True)

        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.finish(reset_current=True)

    def start(self, mark_as_current: bool = False):
        if mark_as_current:
            self._prev_context_token = Scope.set_current_trace(self)

    def finish(self, reset_current: bool = False):
        if reset_current and self._prev_context_token is not None:
            Scope.reset_current_trace(self._prev_context_token)
            self._prev_context_token = None

    @property
    def trace_id(self) -> str:
        """The trace's unique identifier.

        Returns:
            str: A unique ID for this trace.
        """
        return "no-op"

    @property
    def name(self) -> str:
        """The workflow name for this trace.

        Returns:
            str: Human-readable name describing this workflow.
        """
        return "no-op"

    def export(self) -> dict[str, Any] | None:
        """Export the trace data as a dictionary.

        Returns:
            dict | None: Trace data in exportable format, or None if no data.
        """
        return None

    @property
    def tracing_api_key(self) -> str | None:
        return None

trace_id property 

trace_id: str

The trace's unique identifier.

Returns:

Name Type Description
str str

A unique ID for this trace.

name property 

name: str

The workflow name for this trace.

Returns:

Name Type Description
str str

Human-readable name describing this workflow.

export 

export() -> dict[str, Any] | None

Export the trace data as a dictionary.

Returns:

Type Description
dict[str, Any] | None

dict | None: Trace data in exportable format, or None if no data.
Source code in src/agents/tracing/traces.py 
282
283
284
285
286
287
288
def export(self) -> dict[str, Any] | None:
    """Export the trace data as a dictionary.

    Returns:
        dict | None: Trace data in exportable format, or None if no data.
    """
    return None

to_json 

to_json(
    *, include_tracing_api_key: bool = False
) -> dict[str, Any] | None

Serialize trace metadata for persistence or transport.

Parameters:

Name Type Description Default
include_tracing_api_key bool

When True, include the tracing API key. Defaults to False to avoid persisting secrets unintentionally.

 False
Source code in src/agents/tracing/traces.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def to_json(self, *, include_tracing_api_key: bool = False) -> dict[str, Any] | None:
    """Serialize trace metadata for persistence or transport.

    Args:
        include_tracing_api_key: When True, include the tracing API key. Defaults to False
            to avoid persisting secrets unintentionally.
    """
    exported = self.export()
    if exported is None:
        return None
    payload = dict(exported)
    if include_tracing_api_key and self.tracing_api_key:
        payload["tracing_api_key"] = self.tracing_api_key
    return payload

TraceImpl

Bases: Trace

A trace that will be recorded by the tracing library.

Source code in src/agents/tracing/traces.py 
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
class TraceImpl(Trace):
    """
    A trace that will be recorded by the tracing library.
    """

    __slots__ = (
        "_name",
        "_trace_id",
        "_tracing_api_key",
        "group_id",
        "metadata",
        "_prev_context_token",
        "_processor",
        "_started",
    )

    def __init__(
        self,
        name: str,
        trace_id: str | None,
        group_id: str | None,
        metadata: dict[str, Any] | None,
        processor: TracingProcessor,
        tracing_api_key: str | None = None,
    ):
        self._name = name
        self._trace_id = trace_id or util.gen_trace_id()
        self._tracing_api_key = tracing_api_key
        self.group_id = group_id
        self.metadata = metadata
        self._prev_context_token: contextvars.Token[Trace | None] | None = None
        self._processor = processor
        self._started = False

    @property
    def trace_id(self) -> str:
        return self._trace_id

    @property
    def name(self) -> str:
        return self._name

    @property
    def tracing_api_key(self) -> str | None:
        return self._tracing_api_key

    def start(self, mark_as_current: bool = False):
        if self._started:
            return

        self._started = True
        self._processor.on_trace_start(self)

        if mark_as_current:
            self._prev_context_token = Scope.set_current_trace(self)

    def finish(self, reset_current: bool = False):
        if not self._started:
            return

        self._processor.on_trace_end(self)

        if reset_current and self._prev_context_token is not None:
            Scope.reset_current_trace(self._prev_context_token)
            self._prev_context_token = None

    def __enter__(self) -> Trace:
        if self._started:
            if not self._prev_context_token:
                logger.error("Trace already started but no context token set")
            return self

        self.start(mark_as_current=True)
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.finish(reset_current=exc_type is not GeneratorExit)

    def export(self) -> dict[str, Any] | None:
        return {
            "object": "trace",
            "id": self.trace_id,
            "workflow_name": self.name,
            "group_id": self.group_id,
            "metadata": self.metadata,
        }

to_json 

to_json(
    *, include_tracing_api_key: bool = False
) -> dict[str, Any] | None

Serialize trace metadata for persistence or transport.

Parameters:

Name Type Description Default
include_tracing_api_key bool

When True, include the tracing API key. Defaults to False to avoid persisting secrets unintentionally.

 False
Source code in src/agents/tracing/traces.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def to_json(self, *, include_tracing_api_key: bool = False) -> dict[str, Any] | None:
    """Serialize trace metadata for persistence or transport.

    Args:
        include_tracing_api_key: When True, include the tracing API key. Defaults to False
            to avoid persisting secrets unintentionally.
    """
    exported = self.export()
    if exported is None:
        return None
    payload = dict(exported)
    if include_tracing_api_key and self.tracing_api_key:
        payload["tracing_api_key"] = self.tracing_api_key
    return payload