j7GUdZddlmZmZmZmZmZmZmZm Z m Z ddl m Z ddl m Z ddl mZddl mZddlmZddlmZmZddlmZdd lmZdd lmZed Zed Zgd Zee eefe d<GddeZ!deddfdZ"dddddddddee#dee#deee#e#fdee#deee#dee#de$deefdZ%eddddddddddee#dee#deee#e#fdee#deee#dee#de$d ee!deeeeffd!Z&d"ej'dee#e e#ee#fffd#Z(d$e#d%e e#ee#ee#e#ffd"ej'd&ej)de$dej'f d'Z*d%ed$e#dee e#ee#ffd(Z+d%e#d$e#de$fd)Z,d$e#de#fd*Z-d+Z.d$e#de#fd,Z/d$e#dee#fd-Z0d$e#de#fd.Z1dS)/aAttribute propagation utilities for Langfuse OpenTelemetry integration. This module provides the `propagate_attributes` context manager for setting trace-level attributes (user_id, session_id, metadata) that automatically propagate to all child spans within the context. ) AnyDict GeneratorListLiteralOptional TypedDictUnioncast)baggagecontext)trace)_RUNTIME_CONTEXT)_AgnosticContextManager_agnosticcontextmanager)LangfuseOtelSpanAttributes)#LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT)langfuse_logger)user_id session_idmetadataversiontags trace_name) experiment_idexperiment_nameexperiment_metadataexperiment_dataset_idexperiment_item_idexperiment_item_metadata#experiment_item_root_observation_id) rrrrrrrrrrr r!r"propagated_keysceZdZUeed<eed<eeeefed<eeed<eed<eeeefed<eed<dS) PropagatedExperimentAttributesrrrrr r!r"N)__name__ __module__ __qualname__str__annotations__rrl/lsinfo/ai/hellotax_ai/data_center/backend/venv/lib/python3.11/site-packages/langfuse/_client/propagation.pyr%r%Ds!$sCx.1111#C=(((&tCH~6666),,,,,,r,r%tokenreturnNcR tj|dS#t$rYdSwxYw)aDetach a context token without emitting noisy async teardown errors. OpenTelemetry tokens are backed by ``contextvars`` and must be detached in the same execution context where they were attached. Async frameworks can legitimately end spans or unwind context managers in a different task/context, in which case detach raises and the public OpenTelemetry helper logs an error. At that point the observation is already completed, so the mismatch is safe to ignore. N)rdetach Exception)r.s r-_detach_context_token_safelyr3Ns@ &&&&&      s  &&Frrrrrr as_baggagerrrrrrr5c .t|||||||S)uPropagate trace-level attributes to all spans created within this context. This context manager sets attributes on the currently active span AND automatically propagates them to all new child spans created within the context. This is the recommended way to set trace-level attributes like user_id, session_id, and metadata dimensions that should be consistently applied across all observations in a trace. **IMPORTANT**: Call this as early as possible within your trace/workflow. Only the currently active span and spans created after entering this context will have these attributes. Pre-existing spans will NOT be retroactively updated. **Why this matters**: Langfuse aggregation queries (e.g., total cost by user_id, filtering by session_id) only include observations that have the attribute set. If you call `propagate_attributes` late in your workflow, earlier spans won't be included in aggregations for that attribute. Args: user_id: User identifier to associate with all spans in this context. Must be US-ASCII string, ≤200 characters. Use this to track which user generated each trace and enable e.g. per-user cost/performance analysis. session_id: Session identifier to associate with all spans in this context. Must be US-ASCII string, ≤200 characters. Use this to group related traces within a user session (e.g., a conversation thread, multi-turn interaction). metadata: Additional key-value metadata to propagate to all spans. - Keys and values must be US-ASCII strings - All values must be ≤200 characters - Use for dimensions like internal correlating identifiers - AVOID: large payloads, sensitive data, non-string values (will be dropped with warning) version: Version identfier for parts of your application that are independently versioned, e.g. agents tags: List of tags to categorize the group of observations trace_name: Name to assign to the trace. Must be US-ASCII string, ≤200 characters. Use this to set a consistent trace name for all spans created within this context. as_baggage: If True, propagates attributes using OpenTelemetry baggage for cross-process/service propagation. **Security warning**: When enabled, attribute values are added to HTTP headers on ALL outbound requests. Only enable if values are safe to transmit via HTTP headers and you need cross-service tracing. Default: False. Returns: Context manager that propagates attributes to all child spans. Example: Basic usage with user and session tracking: ```python from langfuse import Langfuse langfuse = Langfuse() # Set attributes early in the trace with langfuse.start_as_current_observation(name="user_workflow") as span: with langfuse.propagate_attributes( user_id="user_123", session_id="session_abc", metadata={"experiment": "variant_a", "environment": "production"} ): # All spans created here will have user_id, session_id, and metadata with langfuse.start_observation(name="llm_call") as llm_span: # This span inherits: user_id, session_id, experiment, environment ... with langfuse.start_generation(name="completion") as gen: # This span also inherits all attributes ... ``` Late propagation (anti-pattern): ```python with langfuse.start_as_current_observation(name="workflow") as span: # These spans WON'T have user_id early_span = langfuse.start_observation(name="early_work") early_span.end() # Set attributes in the middle with langfuse.propagate_attributes(user_id="user_123"): # Only spans created AFTER this point will have user_id late_span = langfuse.start_observation(name="late_work") late_span.end() # Result: Aggregations by user_id will miss "early_work" span ``` Cross-service propagation with baggage (advanced): ```python # Service A - originating service with langfuse.start_as_current_observation(name="api_request"): with langfuse.propagate_attributes( user_id="user_123", session_id="session_abc", as_baggage=True # Propagate via HTTP headers ): # Make HTTP request to Service B response = requests.get("https://service-b.example.com/api") # user_id and session_id are now in HTTP headers # Service B - downstream service # OpenTelemetry will automatically extract baggage from HTTP headers # and propagate to spans in Service B ``` Note: - **Validation**: All attribute values (user_id, session_id, metadata values) must be strings ≤200 characters. Invalid values will be dropped with a warning logged. Ensure values meet constraints before calling. - **OpenTelemetry**: This uses OpenTelemetry context propagation under the hood, making it compatible with other OTel-instrumented libraries. Raises: No exceptions are raised. Invalid values are logged as warnings and dropped. r4)_propagate_attributesr4s r-propagate_attributesr8^s1t !    r,)rrrrrrr5 experimentr9c#Ktj}tj} |||||d} d|i} |r|D]\} } | dvr6t t tttf| | | <?t t ttttf| | | <d| D} | D],\} } t| | }|t| ||| |}-| D]U\}}|i}|D] \} } t| |d| r| || <!|rt|||| |}Vtj|} dVt|dS#t|wxYw) N)rrrrrr)rr!ci|] \}}||| SNr+).0kvs r- z)_propagate_attributes.. s&$$$A1r,valuekey)rCrBrspanr5.r )otel_context_api get_currentotel_trace_apiget_current_spanitemsr rrr)r r_validate_propagated_value_set_propagated_attribute_validate_string_valueattachr3)rrrrrrr5r9r current_spanpropagated_string_attributespropagated_metadata_attributesrCrBvalidated_value metadata_keymetadata_valuevalidated_metadatar.s r-r7r7sf*,,G!244L  PP  HK" $**,,  JCIII6:T#s(^,e77.s3359U3S >23U55,S11 $$5;;==$$$ 388::   U45cJJJ  &/%!% G)G(L(L(N(N$ n  ! -/(..00 0 0JC%E,7N7N7N7NOOO 0*/"3'  / (!% G  #G 4 4 4E,  %U+++++$U++++s *F??Grci}tj|}|D]`\}}|trAt |}|r0t |ttfr|nt|||<atD]}t|}tj ||}|*t |tr4t|}|D]\} } | ||d| <st|}t |ttfr|nt|||<tj|vrt"|tj<|S)Nr )rCrrE)r get_allrJ startswithLANGFUSE_BAGGAGE_PREFIX_get_span_key_from_baggage_key isinstancer)listr#_get_propagated_context_keyrF get_valuedict_get_propagated_span_keyr#EXPERIMENT_ITEM_ROOT_OBSERVATION_IDr ENVIRONMENT) rpropagated_attributesbaggage_entries baggage_key baggage_valuespan_keyrC context_keyrBr>r?s r-'_get_propagated_attributes_from_contextri7s?Aog666O&5&;&;&=&=  " ]  ! !"9 : : 5kBBH "-#t==,MM]++&h/1#66  *{GLLL =  eT " " /44H  = =1;<%&7&7A&7&788 =044H$EC;77GSZZ "( + + #F  ! ! 0 8DE ! r,rCrBrDc t|}t|}t|}t|tr.t tt j|pi}||z}t|tr[t tt j|pg t } | fd|D| }t j |||}|w| rct|tr7| D]!\} } | |d| | "n| |||rct|tr7| D]!\} } tj|d| | |}"ntj|||}|S)Nc3$K|] }|v|V dSr<r+)r=tagexisting_tags_in_contexts r- z,_set_propagated_attribute..s.WW33>V3V3V33V3V3V3VWWr,)rCrBrrErCrB_)namerBr)r]r`_get_propagated_baggage_keyr[r_r rFr^r\extend set_value is_recordingrJ set_attributeotel_baggage_api set_baggage) rCrBrrDr5rhrgreexisting_metadata_in_context merged_tagsr>r?rms @r-rLrLjs9.c22K',,H-c22K%5'+ ",[99?R( ( $-u4%#' ",[99?R$ $  344 WWWW%WWWWWW( G D--// eT " " :   1""#))a))#    85  9 9 9  eT " "    1*6'--!--Q  '2 wG Nr,cTt|tr%fd|D}t|dkr|ndSt|tst jdddSt|dkr*t jddt|ddS|S)Nc6g|]}t||S)ro)rM)r=r?rCs r- z._validate_propagated_value..s<    63a H H H    r,rPropagated attribute '(' value is not a string. Dropping value. ' value is over 200 characters ( chars). Dropping value.)r[r\lenr)rwarning)rBrCvalidated_valuess ` r-rKrKs%G       $''7#8#81#<#<$F eS ! ! RS R R R   t 5zzC nS n n#e** n n n   t Lr,ct|tstjd|ddSt |dkr*tjd|dt |ddSdS)Nr~rFrrrT)r[r)rrrrAs r-rMrMs eS ! ! RS R R R   u 5zzC nS n n#e** n n n   u 4r,c d|S)Nzlangfuse.propagated.r+rCs r-r]r]s '# ' ''r, langfuse_ct|Sr<)rYrs r-rrrrs% ,s , ,,r,c$|tsdS|ttd}dD]G}|d}||r+t|d|t|dcSHt|S)N)rrr!rprE)rXrYrr`)rCsuffixrSbaggage_metadata_prefixs r-rZrZs >>1 2 2t,--// 0FW %1"4"4"4   4 5 5 +L99<<#566889<<     $F + ++r,cntjtjtjtjtjtjtjtjtj tj tj tj tj d |ptjd|S)N) rrrrrrrrrrr r!r"rE)rTRACE_SESSION_ID TRACE_USER_IDVERSION TRACE_TAGS TRACE_NAMETRACE_METADATA EXPERIMENT_IDEXPERIMENT_NAMEEXPERIMENT_METADATAEXPERIMENT_DATASET_IDEXPERIMENT_ITEM_IDEXPERIMENT_ITEM_METADATAragetrs r-r`r`s0A-;-5*50;.=3A5E9M!;!Q8K$>$W/I/m   c#hh G0>FFFFGr,)2__doc__typingrrrrrrr r r opentelemetryr rwrrFrrHopentelemetry.contextropentelemetry.util._decoratorrrlangfuse._client.attributesrlangfuse._client.constantsrlangfuse.loggerrPropagatedKeysInternalPropagatedKeysr#r*r%r3r)boolr8r7ContextriSpanrLrKrMr]rYrrrZr`r+r,r-rsEYXXXXXXXXXXXXXXXXXXXXX322222 CBBBBBJJJJJJ++++++!+HHHeN,BBCD"-----Y---         $" $)-! $ $BBB c]B BtCH~& B c] B 49  B BBS!BBBBJ" $)-! $ $;?P,P,P, c]P, P,tCH~& P, c] P, 49  P, P,P,78P,sC}P,P,P,P,f0!  %0! #uS$s)^$ $%0!0!0!0!f? ? d3ic3h/ 0? % ?   ?  ?????D eCcN#$2 S s t     (S(S((((&-S-S----,, ,,,,&G#G#GGGGGGr,