Skip to content

Commit d852fda

Browse files
niklassemmlerclaude
andcommitted
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>
1 parent ca577cd commit d852fda

3 files changed

Lines changed: 44 additions & 2 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()`, `update()`, and `propagate_attributes()`, where it is applied to each propagated trace metadata value separately (keys are kept).
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). For propagated metadata, the mask comes from the client for the public key in the execution context, otherwise from the only initialized client. With several clients and no public key in context, or with no client yet, propagated metadata is not masked. To avoid this, pass `langfuse_public_key` via `@observe` or use a single client; `mask_otel_spans` also sees these attributes at export, but not outgoing baggage.
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/propagation.py‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,11 @@ def propagate_attributes(
162162
- Values are coerced to strings
163163
- If the client has a `mask` function, it is applied to each value
164164
(not the key) before coercion; if it raises, that value becomes
165-
"<fully masked due to failed mask function>"
165+
"<fully masked due to failed mask function>". The mask comes from
166+
the client for the public key in the execution context, otherwise
167+
the only initialized client. With several clients and no public key
168+
in context, or with no client yet, values are not masked; pass
169+
`langfuse_public_key` via `@observe` or use a single client
166170
- Coerced values must be ≤200 characters
167171
- Use for dimensions like internal correlating identifiers
168172
- AVOID: large payloads or sensitive data
@@ -453,6 +457,8 @@ def _get_current_mask() -> Optional[MaskFunction]:
453457
Uses the public key in the execution context, otherwise the only initialized
454458
client. With no client, or several clients and no public key, there is no mask.
455459
"""
460+
# Known limitation: in those cases propagated metadata is exported unmasked
461+
# even if a client has a mask, since there is no single client to pick
456462
# Imported here to avoid a circular import via the span processor
457463
from langfuse._client.get_client import _current_public_key
458464
from langfuse._client.resource_manager import LangfuseResourceManager

‎tests/unit/test_propagate_attributes.py‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3889,6 +3889,42 @@ def mask(*, data, **kwargs):
38893889
span_data = self.get_span_by_name(memory_exporter, "child-span")
38903890
assert self.get_trace_metadata(span_data) == {"long": "a" * 10}
38913891

3892+
def test_mask_with_several_clients_needs_public_key_in_context(
3893+
self, monkeypatch, tracer_provider, mock_processor_init, memory_exporter
3894+
):
3895+
"""Verify the known limitation: several clients and no key means no mask."""
3896+
from langfuse import Langfuse
3897+
from langfuse._client.get_client import _set_current_public_key
3898+
3899+
monkeypatch.setenv("LANGFUSE_SECRET_KEY", "test-secret-key")
3900+
masked_client = Langfuse(
3901+
public_key="pk-masked",
3902+
secret_key="test-secret-key",
3903+
host="http://test-host",
3904+
tracer_provider=tracer_provider,
3905+
mask=lambda *, data, **kwargs: None if data is None else "***",
3906+
)
3907+
Langfuse(
3908+
public_key="pk-other",
3909+
secret_key="test-secret-key",
3910+
host="http://test-host",
3911+
tracer_provider=tracer_provider,
3912+
)
3913+
3914+
with masked_client.start_as_current_observation(name="no-key-span"):
3915+
with propagate_attributes(metadata={"api_key": "secret"}):
3916+
pass
3917+
3918+
with _set_current_public_key("pk-masked"):
3919+
with masked_client.start_as_current_observation(name="key-span"):
3920+
with propagate_attributes(metadata={"api_key": "secret"}):
3921+
pass
3922+
3923+
no_key_span = self.get_span_by_name(memory_exporter, "no-key-span")
3924+
assert self.get_trace_metadata(no_key_span) == {"api_key": "secret"}
3925+
key_span = self.get_span_by_name(memory_exporter, "key-span")
3926+
assert self.get_trace_metadata(key_span) == {"api_key": "***"}
3927+
38923928
def test_no_mask_leaves_metadata_unchanged(self, langfuse_client, memory_exporter):
38933929
"""Verify metadata is unchanged when no mask is configured."""
38943930
with langfuse_client.start_as_current_observation(name="parent-span"):

0 commit comments

Comments
 (0)