Skip to content

Commit ca577cd

Browse files
niklassemmlerclaude
andcommitted
fix(tracing): apply mask to propagated trace metadata
propagate_attributes now applies the client's mask to each propagated trace metadata value (keys are kept), on the raw value before serialization and the 200 character check. If the mask raises, only that value becomes the fallback string. The masked values are stored in the context and baggage, so the current span, child spans, and outgoing baggage all carry them. Matches langfuse-js #1003. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 47d263b commit ca577cd

5 files changed

Lines changed: 188 additions & 5 deletions

File tree

‎langfuse/_client/client.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@ class Langfuse:
212212
release (Optional[str]): Release version/hash of your application. Used for grouping analytics by release.
213213
media_upload_thread_count (Optional[int]): Number of background threads for handling media uploads. Defaults to 1. Can also be set via LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT environment variable.
214214
sample_rate (Optional[float]): Sampling rate for traces (0.0 to 1.0). Defaults to 1.0 (100% of traces are sampled). Can also be set via LANGFUSE_SAMPLE_RATE environment variable.
215-
mask (Optional[MaskFunction]): Function to mask sensitive data synchronously when Langfuse SDK attributes are created. This applies only to data set through Langfuse SDK APIs such as `start_observation()` and `update()`.
215+
mask (Optional[MaskFunction]): Function to mask sensitive data synchronously when Langfuse SDK attributes are created. This applies only to data set through Langfuse SDK APIs such as `start_observation()`, `update()`, and `propagate_attributes()`, where it is applied to each propagated trace metadata value separately (keys are kept).
216216
mask_otel_spans (Optional[MaskOtelSpansFunction]): Synchronous export-stage hook for masking raw OpenTelemetry span attributes before this Langfuse client sends them to Langfuse. Use this for spans created by third-party OpenTelemetry instrumentations, or when you need to inspect final span attributes after export filtering and Langfuse media handling. It does not modify spans already exported through other OpenTelemetry exporters.
217217
218218
The hook receives one OpenTelemetry export batch. A batch is not guaranteed to contain a complete trace, request, or Langfuse observation tree. The hook usually runs on the OpenTelemetry batch span processor worker thread; during `flush()` and shutdown it may run on the caller thread. Keep it synchronous, deterministic, and fast.

‎langfuse/_client/constants.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111

1212
LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT = "sdk-experiment"
1313

14+
MASK_FALLBACK_VALUE = "<fully masked due to failed mask function>"
15+
1416
"""Note: this type is used with .__args__ / get_args in some cases and therefore must remain flat"""
1517
ObservationTypeGenerationLike: TypeAlias = Literal[
1618
"generation",

‎langfuse/_client/propagation.py‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,14 @@
4040
)
4141

4242
from langfuse._client.attributes import LangfuseOtelSpanAttributes
43-
from langfuse._client.constants import LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT
43+
from langfuse._client.constants import (
44+
LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT,
45+
MASK_FALLBACK_VALUE,
46+
)
4447
from langfuse._utils.serializer import EventSerializer
4548
from langfuse.logger import langfuse_logger
4649
from langfuse.model import PromptClient
50+
from langfuse.types import MaskFunction
4751

4852
PropagatedKeys = Literal[
4953
"user_id",
@@ -156,6 +160,9 @@ def propagate_attributes(
156160
metadata: Additional key-value metadata to propagate to all spans.
157161
- Keys must be US-ASCII strings
158162
- Values are coerced to strings
163+
- If the client has a `mask` function, it is applied to each value
164+
(not the key) before coercion; if it raises, that value becomes
165+
"<fully masked due to failed mask function>"
159166
- Coerced values must be ≤200 characters
160167
- Use for dimensions like internal correlating identifiers
161168
- AVOID: large payloads or sensitive data
@@ -391,13 +398,20 @@ def _propagate_attributes(
391398
as_baggage=as_baggage,
392399
)
393400

401+
# Mask once here: the masked values are stored in the context and baggage,
402+
# so the current span and every child span receive them
403+
mask = _get_current_mask() if metadata else None
404+
394405
for metadata_key, metadata_value in propagated_metadata_attributes.items():
395406
if metadata_value is None:
396407
continue
397408

398409
validated_metadata: Dict[str, str] = {}
399410

400411
for key, value in metadata_value.items():
412+
if mask is not None and metadata_key == "metadata":
413+
value = _mask_propagated_metadata_value(mask=mask, value=value)
414+
401415
serialized_value = _serialize_propagated_metadata_value(value)
402416

403417
if serialized_value is None:
@@ -433,6 +447,43 @@ def _propagate_attributes(
433447
_detach_context_token_safely(token)
434448

435449

450+
def _get_current_mask() -> Optional[MaskFunction]:
451+
"""Return the mask of the client that get_client() would resolve, if any.
452+
453+
Uses the public key in the execution context, otherwise the only initialized
454+
client. With no client, or several clients and no public key, there is no mask.
455+
"""
456+
# Imported here to avoid a circular import via the span processor
457+
from langfuse._client.get_client import _current_public_key
458+
from langfuse._client.resource_manager import LangfuseResourceManager
459+
460+
with LangfuseResourceManager._lock:
461+
instances = LangfuseResourceManager._instances
462+
public_key = _current_public_key.get(None)
463+
464+
if public_key:
465+
instance = instances.get(public_key)
466+
elif len(instances) == 1:
467+
instance = next(iter(instances.values()))
468+
else:
469+
instance = None
470+
471+
return instance.mask if instance is not None else None
472+
473+
474+
def _mask_propagated_metadata_value(*, mask: MaskFunction, value: Any) -> Any:
475+
try:
476+
return mask(data=value)
477+
except Exception as e:
478+
langfuse_logger.error(
479+
"Masking error: Custom mask function threw exception when processing "
480+
"propagated metadata. Using fallback masking. Error: %s",
481+
e,
482+
)
483+
484+
return MASK_FALLBACK_VALUE
485+
486+
436487
def _extract_propagated_prompt(
437488
prompt: Union[PromptClient, Mapping[str, Any]],
438489
) -> Optional[Tuple[str, int]]:

‎langfuse/_client/span.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
create_trace_attributes,
4545
)
4646
from langfuse._client.constants import (
47+
MASK_FALLBACK_VALUE,
4748
ObservationTypeGenerationLike,
4849
ObservationTypeLiteral,
4950
ObservationTypeLiteralNoEvent,
@@ -538,14 +539,13 @@ def _mask_attribute(
538539
"data. Using fallback masking. Error: %s",
539540
e,
540541
)
541-
fallback = "<fully masked due to failed mask function>"
542542

543543
# Dict metadata is written per key, so mask each key instead of
544544
# writing a plain string to the bare metadata attribute
545545
if field == "metadata" and isinstance(data, dict):
546-
return {key: fallback for key in data}
546+
return {key: MASK_FALLBACK_VALUE for key in data}
547547

548-
return fallback
548+
return MASK_FALLBACK_VALUE
549549

550550
def _process_media_in_attribute(
551551
self,

‎tests/unit/test_propagate_attributes.py‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3769,3 +3769,133 @@ def test_prompt_composes_with_outer_propagated_attributes(
37693769
self.verify_missing_attribute(
37703770
after_span, LangfuseOtelSpanAttributes.OBSERVATION_PROMPT_NAME
37713771
)
3772+
3773+
3774+
class TestPropagateAttributesMask(TestPropagateAttributesBase):
3775+
"""Tests for applying the client's mask to propagated trace metadata."""
3776+
3777+
MASK_FALLBACK = "<fully masked due to failed mask function>"
3778+
3779+
@pytest.fixture
3780+
def masked_langfuse_client(self, monkeypatch, tracer_provider, mock_processor_init):
3781+
"""Create a mocked Langfuse client with a configurable mask."""
3782+
from langfuse import Langfuse
3783+
3784+
def _create_client(mask):
3785+
monkeypatch.setenv("LANGFUSE_PUBLIC_KEY", "test-public-key")
3786+
monkeypatch.setenv("LANGFUSE_SECRET_KEY", "test-secret-key")
3787+
3788+
return Langfuse(
3789+
public_key="test-public-key",
3790+
secret_key="test-secret-key",
3791+
host="http://test-host",
3792+
tracing_enabled=True,
3793+
tracer_provider=tracer_provider,
3794+
mask=mask,
3795+
)
3796+
3797+
return _create_client
3798+
3799+
def get_trace_metadata(self, span_data: dict) -> dict:
3800+
prefix = f"{LangfuseOtelSpanAttributes.TRACE_METADATA}."
3801+
return {
3802+
key[len(prefix) :]: value
3803+
for key, value in span_data["attributes"].items()
3804+
if key.startswith(prefix)
3805+
}
3806+
3807+
def test_mask_applies_to_current_and_child_spans(
3808+
self, masked_langfuse_client, memory_exporter
3809+
):
3810+
"""Verify each raw value is masked once and keys are kept."""
3811+
masked_values = []
3812+
3813+
def mask(*, data, **kwargs):
3814+
# Observation input/output/metadata are masked too and are None here
3815+
if data is None:
3816+
return None
3817+
masked_values.append(data)
3818+
if isinstance(data, dict):
3819+
return {k: "***" if k == "token" else v for k, v in data.items()}
3820+
return data.replace("secret", "***")
3821+
3822+
langfuse_client = masked_langfuse_client(mask)
3823+
3824+
with langfuse_client.start_as_current_observation(name="parent-span"):
3825+
with propagate_attributes(
3826+
metadata={"api_key": "secret-key", "auth": {"token": "secret"}}
3827+
):
3828+
child = langfuse_client.start_observation(name="child-span")
3829+
child.end()
3830+
3831+
expected = {"api_key": "***-key", "auth": '{"token":"***"}'}
3832+
for name in ("parent-span", "child-span"):
3833+
span_data = self.get_span_by_name(memory_exporter, name)
3834+
assert self.get_trace_metadata(span_data) == expected
3835+
3836+
assert masked_values == ["secret-key", {"token": "secret"}]
3837+
3838+
def test_mask_applies_to_baggage(self, masked_langfuse_client):
3839+
"""Verify baggage carries masked values."""
3840+
from opentelemetry import baggage
3841+
3842+
langfuse_client = masked_langfuse_client(lambda *, data, **kwargs: "***")
3843+
3844+
with langfuse_client.start_as_current_observation(name="parent-span"):
3845+
with propagate_attributes(metadata={"api_key": "secret"}, as_baggage=True):
3846+
assert baggage.get_baggage("langfuse_metadata_api_key") == "***"
3847+
3848+
def test_failed_mask_replaces_only_that_value(
3849+
self, masked_langfuse_client, memory_exporter
3850+
):
3851+
"""Verify a throwing mask gives the fallback for that value only."""
3852+
3853+
def mask(*, data, **kwargs):
3854+
if data == "secret":
3855+
raise ValueError("mask failed")
3856+
return data
3857+
3858+
langfuse_client = masked_langfuse_client(mask)
3859+
3860+
with langfuse_client.start_as_current_observation(name="parent-span"):
3861+
with propagate_attributes(metadata={"api_key": "secret", "env": "prod"}):
3862+
child = langfuse_client.start_observation(name="child-span")
3863+
child.end()
3864+
3865+
for name in ("parent-span", "child-span"):
3866+
span_data = self.get_span_by_name(memory_exporter, name)
3867+
assert self.get_trace_metadata(span_data) == {
3868+
"api_key": self.MASK_FALLBACK,
3869+
"env": "prod",
3870+
}
3871+
3872+
def test_length_limit_applies_to_masked_value(
3873+
self, masked_langfuse_client, memory_exporter
3874+
):
3875+
"""Verify the 200 character limit is checked after masking."""
3876+
3877+
def mask(*, data, **kwargs):
3878+
if data is None:
3879+
return None
3880+
return "x" * 201 if data == "expand" else data[:10]
3881+
3882+
langfuse_client = masked_langfuse_client(mask)
3883+
3884+
with langfuse_client.start_as_current_observation(name="parent-span"):
3885+
with propagate_attributes(metadata={"long": "a" * 300, "short": "expand"}):
3886+
child = langfuse_client.start_observation(name="child-span")
3887+
child.end()
3888+
3889+
span_data = self.get_span_by_name(memory_exporter, "child-span")
3890+
assert self.get_trace_metadata(span_data) == {"long": "a" * 10}
3891+
3892+
def test_no_mask_leaves_metadata_unchanged(self, langfuse_client, memory_exporter):
3893+
"""Verify metadata is unchanged when no mask is configured."""
3894+
with langfuse_client.start_as_current_observation(name="parent-span"):
3895+
with propagate_attributes(metadata={"api_key": "secret", "n": 1}):
3896+
child = langfuse_client.start_observation(name="child-span")
3897+
child.end()
3898+
3899+
for name in ("parent-span", "child-span"):
3900+
span_data = self.get_span_by_name(memory_exporter, name)
3901+
assert self.get_trace_metadata(span_data) == {"api_key": "secret", "n": "1"}

0 commit comments

Comments
 (0)