o h@sddlmZddlZddlZddlmZddlmZddlmZddl m Z dd l m Z Gd d d ej ZGd d d eZeZGdddeZdS)) annotationsN)Any)logger)util)TracingProcessor)Scopec@seZdZdZejdddZejddZejddd d Zejddd dZ e ejdddZ e ejdddZ ejdddZ dS)Tracea: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 returncCdSNselfrrV/var/www/html/openai_agents/venv/lib/python3.10/site-packages/agents/tracing/traces.py __enter__-zTrace.__enter__cCr r rrexc_typeexc_valexc_tbrrr__exit__1rzTrace.__exit__Fmark_as_currentboolcCdS)aStart 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 Nrrrrrrstart5 z Trace.start reset_currentcCr)ajFinish 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 NrrrrrrfinishDrz Trace.finishstrcCr)a=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 Nrrrrrtrace_idSrzTrace.trace_idcCr)aWGet 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 Nrrrrrnamebrz Trace.namedict[str, Any] | NonecCr)aKExport 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 Nrrrrrexportqs z Trace.exportNr r Frrrrr r"r r%)__name__ __module__ __qualname____doc__abcabstractmethodrrrr!propertyr#r$r&rrrrr s$    r c@sheZdZdZddZdddZdd Zddd dZddddZe dddZ e dddZ d ddZ dS)! NoOpTraceaA 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") ``` cCsd|_d|_dSNF)_started_prev_context_tokenrrrr__init__s zNoOpTrace.__init__r r cCs0|jr |js td|Sd|_|jdd|SNz.Trace already started but no context token setT)rr6r7rerrorrrrrrrs  zNoOpTrace.__enter__cCs|jdddS)NTr)r!rrrrrszNoOpTrace.__exit__FrrcCs|r t||_dSdSr )r set_current_tracer7rrrrrszNoOpTrace.startrcCs,|r|jdurt|jd|_dSdSdSr )r7r reset_current_tracer rrrr!s  zNoOpTrace.finishr"cCr)zfThe trace's unique identifier. Returns: str: A unique ID for this trace. no-oprrrrrr#zNoOpTrace.trace_idcCr)z{The workflow name for this trace. Returns: str: Human-readable name describing this workflow. r?rrrrrr$r@zNoOpTrace.namer%cCr)zExport the trace data as a dictionary. Returns: dict | None: Trace data in exportable format, or None if no data. Nrrrrrr&szNoOpTrace.exportNr'r(r)r*r+r,) r-r.r/r0r8rrrr!r3r#r$r&rrrrr4s     r4c@sneZdZdZdZd#d d Zed$ddZed$ddZd%d&ddZ d%d'ddZ d(ddZ ddZ d)d d!Z d"S)* TraceImplz? A trace that will be recorded by the tracing library. )_name _trace_idgroup_idmetadatar7 _processorr6r$r"r# str | NonerDrEr% processorrcCs6||_|pt|_||_||_d|_||_d|_dSr5) rBr gen_trace_idrCrDrEr7rFr6)rr$r#rDrErHrrrr8s zTraceImpl.__init__r cC|jSr )rCrrrrr#zTraceImpl.trace_idcCrJr )rBrrrrr$rKzTraceImpl.nameFrrcCs4|jrdSd|_|j||rt||_dSdS)NT)r6rFon_trace_startr r=r7rrrrrs zTraceImpl.startrcCsB|jsdS|j||r|jdurt|jd|_dSdSdSr )r6rF on_trace_endr7r r>r rrrr!s   zTraceImpl.finishr cCs*|jr |js td|S|jdd|Sr9r:rrrrrs   zTraceImpl.__enter__cCs|j|tuddS)Nr<)r! GeneratorExitrrrrr szTraceImpl.__exit__cCsd|j|j|j|jdS)Ntrace)objectid workflow_namerDrE)r#r$rDrErrrrr&s zTraceImpl.exportN) r$r"r#rGrDrGrEr%rHrr+r(r)r*r'r,)r-r.r/r0 __slots__r8r3r#r$rr!rrr&rrrrrAs      rA) __future__rr1 contextvarstypingrrrprocessor_interfacerscoper ABCr r4 NO_OP_TRACErArrrrs      sE