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 99100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173

classSpan(abc.ABC,Generic[TSpanData]):"""Base class for representing traceable operations with timing and context.    A span represents a single operation within a trace (e.g., an LLM call, tool execution,    or agent run). Spans track timing, relationships between operations, and operation-specific    data.    Type Args:        TSpanData: The type of span-specific data this span contains.    Example:        ```python        # Creating a custom span        with custom_span("database_query", {            "operation": "SELECT",            "table": "users"        }) as span:            results = await db.query("SELECT * FROM users")            span.set_output({"count": len(results)})        # Handling errors in spans        with custom_span("risky_operation") as span:            try:                result = perform_risky_operation()            except Exception as e:                span.set_error({                    "message": str(e),                    "data": {"operation": "risky_operation"}                })                raise        ```        Notes:        - Spans automatically nest under the current trace        - Use context managers for reliable start/finish        - Include relevant data but avoid sensitive information        - Handle errors properly using set_error()    """@property@abc.abstractmethoddeftrace_id(self)->str:"""The ID of the trace this span belongs to.        Returns:            str: Unique identifier of the parent trace.        """pass@property@abc.abstractmethoddefspan_id(self)->str:"""Unique identifier for this span.        Returns:            str: The span's unique ID within its trace.        """pass@property@abc.abstractmethoddefspan_data(self)->TSpanData:"""Operation-specific data for this span.        Returns:            TSpanData: Data specific to this type of span (e.g., LLM generation data).        """pass@abc.abstractmethoddefstart(self,mark_as_current:bool=False):"""        Start the span.        Args:            mark_as_current: If true, the span will be marked as the current span.        """pass@abc.abstractmethoddeffinish(self,reset_current:bool=False)->None:"""        Finish the span.        Args:            reset_current: If true, the span will be reset as the current span.        """pass@abc.abstractmethoddef__enter__(self)->Span[TSpanData]:pass@abc.abstractmethoddef__exit__(self,exc_type,exc_val,exc_tb):pass@property@abc.abstractmethoddefparent_id(self)->str|None:"""ID of the parent span, if any.        Returns:            str | None: The parent span's ID, or None if this is a root span.        """pass@abc.abstractmethoddefset_error(self,error:SpanError)->None:pass@property@abc.abstractmethoddeferror(self)->SpanError|None:"""Any error that occurred during span execution.        Returns:            SpanError | None: Error details if an error occurred, None otherwise.        """pass@abc.abstractmethoddefexport(self)->dict[str,Any]|None:pass@property@abc.abstractmethoddefstarted_at(self)->str|None:"""When the span started execution.        Returns:            str | None: ISO format timestamp of span start, None if not started.        """pass@property@abc.abstractmethoddefended_at(self)->str|None:"""When the span finished execution.        Returns:            str | None: ISO format timestamp of span end, None if not finished.        """pass

176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244

classNoOpSpan(Span[TSpanData]):"""A no-op implementation of Span that doesn't record any data.    Used when tracing is disabled but span operations still need to work.    Args:        span_data: The operation-specific data for this span.    """__slots__=("_span_data","_prev_span_token")def__init__(self,span_data:TSpanData):self._span_data=span_dataself._prev_span_token:contextvars.Token[Span[TSpanData]|None]|None=None@propertydeftrace_id(self)->str:return"no-op"@propertydefspan_id(self)->str:return"no-op"@propertydefspan_data(self)->TSpanData:returnself._span_data@propertydefparent_id(self)->str|None:returnNonedefstart(self,mark_as_current:bool=False):ifmark_as_current:self._prev_span_token=Scope.set_current_span(self)deffinish(self,reset_current:bool=False)->None:ifreset_currentandself._prev_span_tokenisnotNone:Scope.reset_current_span(self._prev_span_token)self._prev_span_token=Nonedef__enter__(self)->Span[TSpanData]:self.start(mark_as_current=True)returnselfdef__exit__(self,exc_type,exc_val,exc_tb):reset_current=Trueifexc_typeisGeneratorExit:logger.debug("GeneratorExit, skipping span reset")reset_current=Falseself.finish(reset_current=reset_current)defset_error(self,error:SpanError)->None:pass@propertydeferror(self)->SpanError|None:returnNonedefexport(self)->dict[str,Any]|None:returnNone@propertydefstarted_at(self)->str|None:returnNone@propertydefended_at(self)->str|None:returnNone

247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352

classSpanImpl(Span[TSpanData]):__slots__=("_trace_id","_span_id","_parent_id","_started_at","_ended_at","_error","_prev_span_token","_processor","_span_data",)def__init__(self,trace_id:str,span_id:str|None,parent_id:str|None,processor:TracingProcessor,span_data:TSpanData,):self._trace_id=trace_idself._span_id=span_idorutil.gen_span_id()self._parent_id=parent_idself._started_at:str|None=Noneself._ended_at:str|None=Noneself._processor=processorself._error:SpanError|None=Noneself._prev_span_token:contextvars.Token[Span[TSpanData]|None]|None=Noneself._span_data=span_data@propertydeftrace_id(self)->str:returnself._trace_id@propertydefspan_id(self)->str:returnself._span_id@propertydefspan_data(self)->TSpanData:returnself._span_data@propertydefparent_id(self)->str|None:returnself._parent_iddefstart(self,mark_as_current:bool=False):ifself.started_atisnotNone:logger.warning("Span already started")returnself._started_at=util.time_iso()self._processor.on_span_start(self)ifmark_as_current:self._prev_span_token=Scope.set_current_span(self)deffinish(self,reset_current:bool=False)->None:ifself.ended_atisnotNone:logger.warning("Span already finished")returnself._ended_at=util.time_iso()self._processor.on_span_end(self)ifreset_currentandself._prev_span_tokenisnotNone:Scope.reset_current_span(self._prev_span_token)self._prev_span_token=Nonedef__enter__(self)->Span[TSpanData]:self.start(mark_as_current=True)returnselfdef__exit__(self,exc_type,exc_val,exc_tb):reset_current=Trueifexc_typeisGeneratorExit:logger.debug("GeneratorExit, skipping span reset")reset_current=Falseself.finish(reset_current=reset_current)defset_error(self,error:SpanError)->None:self._error=error@propertydeferror(self)->SpanError|None:returnself._error@propertydefstarted_at(self)->str|None:returnself._started_at@propertydefended_at(self)->str|None:returnself._ended_atdefexport(self)->dict[str,Any]|None:return{"object":"trace.span","id":self.span_id,"trace_id":self.trace_id,"parent_id":self._parent_id,"started_at":self._started_at,"ended_at":self._ended_at,"span_data":self.span_data.export(),"error":self._error,}