Skip to content

Commit e99cc02

Browse files
niklassemmlerclaudecursoragenthassiebp
authored
fix(tracing): mask dict metadata per key when the mask function fails (#1956)
* fix(tracing): mask metadata per key when the mask function fails When a custom mask function raised on dict metadata, the fallback string was written to the bare langfuse.observation.metadata attribute. The server parses that attribute as a JSON object, so the fallback was lost, and nothing showed which keys had been masked. For dict metadata, write the fallback under each key of the failed call instead, so it merges with keys from earlier updates like any other update. Non-dict metadata, input and output keep the plain-string fallback. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * 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> * docs(tracing): document which client's mask applies to propagated metadata The mask for propagated trace metadata comes from the client for the public key in the execution context, otherwise the only initialized client. With several clients and no public key in context, or with no client yet, propagated metadata is not masked. Document this and the workarounds, and pin the behavior with a test. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * revert(tracing): do not mask propagated trace metadata Propagated metadata is passed explicitly by the developer. Masking it adds client-resolution ambiguity and baggage/length-limit ordering complexity, and diverges from the JS SDK. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * fix(tracing): keep string fallback when the mask fails on empty dict metadata Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
1 parent f91a6aa commit e99cc02

3 files changed

Lines changed: 122 additions & 3 deletions

File tree

‎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/span.py‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646
create_trace_attributes,
4747
)
4848
from langfuse._client.constants import (
49+
MASK_FALLBACK_VALUE,
4950
ObservationTypeGenerationLike,
5051
ObservationTypeLiteral,
5152
ObservationTypeLiteralNoEvent,
@@ -706,17 +707,25 @@ def _process_media_and_apply_mask(
706707
The processed and masked data
707708
"""
708709
return self._mask_attribute(
709-
data=self._process_media_in_attribute(data=data, field=field)
710+
data=self._process_media_in_attribute(data=data, field=field), field=field
710711
)
711712

712-
def _mask_attribute(self, *, data: Any) -> Any:
713+
def _mask_attribute(
714+
self,
715+
*,
716+
data: Any,
717+
field: Optional[
718+
Union[Literal["input"], Literal["output"], Literal["metadata"]]
719+
] = None,
720+
) -> Any:
713721
"""Apply the configured mask function to data.
714722
715723
Internal method that applies the client's configured masking function to
716724
the provided data, with error handling and fallback.
717725
718726
Args:
719727
data: The data to mask
728+
field: The attribute the data belongs to
720729
721730
Returns:
722731
The masked data, or the original data if no mask is configured
@@ -733,7 +742,13 @@ def _mask_attribute(self, *, data: Any) -> Any:
733742
e,
734743
)
735744

736-
return "<fully masked due to failed mask function>"
745+
# Dict metadata is written per key, so mask each key instead of
746+
# writing a plain string to the bare metadata attribute. An empty dict
747+
# has no keys to mask, so it keeps the plain string to stay visible
748+
if field == "metadata" and isinstance(data, dict) and data:
749+
return {key: MASK_FALLBACK_VALUE for key in data}
750+
751+
return MASK_FALLBACK_VALUE
737752

738753
def _process_media_in_attribute(
739754
self,

‎tests/unit/test_otel.py‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1980,6 +1980,108 @@ def update_random_metadata(thread_id):
19801980
assert "version" in system_data
19811981
assert "features" in system_data
19821982

1983+
MASK_FALLBACK = "<fully masked due to failed mask function>"
1984+
1985+
def get_metadata_attributes(self, span_data: dict) -> dict:
1986+
prefix = LangfuseOtelSpanAttributes.OBSERVATION_METADATA
1987+
return {
1988+
key: value
1989+
for key, value in span_data["attributes"].items()
1990+
if key == prefix or key.startswith(f"{prefix}.")
1991+
}
1992+
1993+
def test_failed_mask_on_update_masks_each_metadata_key(
1994+
self, configurable_langfuse_client, memory_exporter
1995+
):
1996+
def mask(*, data, **kwargs):
1997+
if isinstance(data, dict) and "secret" in data:
1998+
raise ValueError("mask failed")
1999+
return data
2000+
2001+
langfuse_client = configurable_langfuse_client(mask=mask)
2002+
span = langfuse_client.start_observation(name="mask-fail", metadata={"a": 1})
2003+
span.update(metadata={"secret": "pw", "b": 2})
2004+
span.end()
2005+
2006+
span_data = self.get_spans_by_name(memory_exporter, "mask-fail")[0]
2007+
prefix = LangfuseOtelSpanAttributes.OBSERVATION_METADATA
2008+
assert self.get_metadata_attributes(span_data) == {
2009+
f"{prefix}.a": 1,
2010+
f"{prefix}.secret": self.MASK_FALLBACK,
2011+
f"{prefix}.b": self.MASK_FALLBACK,
2012+
}
2013+
2014+
def test_failed_mask_on_start_masks_each_metadata_key(
2015+
self, configurable_langfuse_client, memory_exporter
2016+
):
2017+
def mask(*, data, **kwargs):
2018+
if isinstance(data, dict):
2019+
raise ValueError("mask failed")
2020+
return data
2021+
2022+
langfuse_client = configurable_langfuse_client(mask=mask)
2023+
span = langfuse_client.start_observation(
2024+
name="mask-fail-start", metadata={"secret": "pw", "b": 2}
2025+
)
2026+
span.end()
2027+
2028+
span_data = self.get_spans_by_name(memory_exporter, "mask-fail-start")[0]
2029+
prefix = LangfuseOtelSpanAttributes.OBSERVATION_METADATA
2030+
assert self.get_metadata_attributes(span_data) == {
2031+
f"{prefix}.secret": self.MASK_FALLBACK,
2032+
f"{prefix}.b": self.MASK_FALLBACK,
2033+
}
2034+
2035+
def test_failed_mask_keeps_string_fallback_for_empty_dict_metadata(
2036+
self, configurable_langfuse_client, memory_exporter
2037+
):
2038+
def mask(*, data, **kwargs):
2039+
if isinstance(data, dict):
2040+
raise ValueError("mask failed")
2041+
return data
2042+
2043+
langfuse_client = configurable_langfuse_client(mask=mask)
2044+
span = langfuse_client.start_observation(
2045+
name="mask-fail-empty-dict", metadata={}
2046+
)
2047+
span.end()
2048+
2049+
span_data = self.get_spans_by_name(memory_exporter, "mask-fail-empty-dict")[0]
2050+
assert self.get_metadata_attributes(span_data) == {
2051+
LangfuseOtelSpanAttributes.OBSERVATION_METADATA: self.MASK_FALLBACK,
2052+
}
2053+
2054+
def test_failed_mask_keeps_string_fallback_for_non_dict_values(
2055+
self, configurable_langfuse_client, memory_exporter
2056+
):
2057+
def mask(*, data, **kwargs):
2058+
if data is not None:
2059+
raise ValueError("mask failed")
2060+
return data
2061+
2062+
langfuse_client = configurable_langfuse_client(mask=mask)
2063+
span = langfuse_client.start_observation(
2064+
name="mask-fail-non-dict",
2065+
input={"secret": "pw"},
2066+
output={"secret": "pw"},
2067+
metadata="plain-string",
2068+
)
2069+
span.end()
2070+
2071+
span_data = self.get_spans_by_name(memory_exporter, "mask-fail-non-dict")[0]
2072+
attributes = span_data["attributes"]
2073+
assert self.get_metadata_attributes(span_data) == {
2074+
LangfuseOtelSpanAttributes.OBSERVATION_METADATA: self.MASK_FALLBACK,
2075+
}
2076+
assert (
2077+
attributes[LangfuseOtelSpanAttributes.OBSERVATION_INPUT]
2078+
== self.MASK_FALLBACK
2079+
)
2080+
assert (
2081+
attributes[LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT]
2082+
== self.MASK_FALLBACK
2083+
)
2084+
19832085

19842086
class TestMultiProjectSetup(TestOTelBase):
19852087
"""Tests for multi-project setup within the same process.

0 commit comments

Comments
 (0)