13 14 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 99100101102103104105106107108109110111112113114115116117118119120121122123124125

classTrace(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.abstractmethoddef__enter__(self)->Trace:pass@abc.abstractmethoddef__exit__(self,exc_type,exc_val,exc_tb):pass@abc.abstractmethoddefstart(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.abstractmethoddeffinish(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.abstractmethoddeftrace_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.abstractmethoddefname(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.abstractmethoddefexport(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

128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194

classNoOpTrace(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=Falseself._prev_context_token:contextvars.Token[Trace|None]|None=Nonedef__enter__(self)->Trace:ifself._started:ifnotself._prev_context_token:logger.error("Trace already started but no context token set")returnselfself._started=Trueself.start(mark_as_current=True)returnselfdef__exit__(self,exc_type,exc_val,exc_tb):self.finish(reset_current=True)defstart(self,mark_as_current:bool=False):ifmark_as_current:self._prev_context_token=Scope.set_current_trace(self)deffinish(self,reset_current:bool=False):ifreset_currentandself._prev_context_tokenisnotNone:Scope.reset_current_trace(self._prev_context_token)self._prev_context_token=None@propertydeftrace_id(self)->str:"""The trace's unique identifier.        Returns:            str: A unique ID for this trace.        """return"no-op"@propertydefname(self)->str:"""The workflow name for this trace.        Returns:            str: Human-readable name describing this workflow.        """return"no-op"defexport(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.        """returnNone

200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278

classTraceImpl(Trace):"""    A trace that will be recorded by the tracing library.    """__slots__=("_name","_trace_id","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,):self._name=nameself._trace_id=trace_idorutil.gen_trace_id()self.group_id=group_idself.metadata=metadataself._prev_context_token:contextvars.Token[Trace|None]|None=Noneself._processor=processorself._started=False@propertydeftrace_id(self)->str:returnself._trace_id@propertydefname(self)->str:returnself._namedefstart(self,mark_as_current:bool=False):ifself._started:returnself._started=Trueself._processor.on_trace_start(self)ifmark_as_current:self._prev_context_token=Scope.set_current_trace(self)deffinish(self,reset_current:bool=False):ifnotself._started:returnself._processor.on_trace_end(self)ifreset_currentandself._prev_context_tokenisnotNone:Scope.reset_current_trace(self._prev_context_token)self._prev_context_token=Nonedef__enter__(self)->Trace:ifself._started:ifnotself._prev_context_token:logger.error("Trace already started but no context token set")returnselfself.start(mark_as_current=True)returnselfdef__exit__(self,exc_type,exc_val,exc_tb):self.finish(reset_current=exc_typeisnotGeneratorExit)defexport(self)->dict[str,Any]|None:return{"object":"trace","id":self.trace_id,"workflow_name":self.name,"group_id":self.group_id,"metadata":self.metadata,}