Skip to content

Commit 91fbc60

Browse files
docs(masking): explain JSON-encoded metadata values in mask_otel_spans (#2013)
* docs(masking): explain JSON-encoded metadata values in mask_otel_spans Co-authored-by: hassieb.pakzad <hassieb.pakzad@clickhouse.com> * docs(masking): guard metadata decode in mask_otel_spans example Co-authored-by: hassieb.pakzad <hassieb.pakzad@clickhouse.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com>
1 parent 49f0f6d commit 91fbc60

2 files changed

Lines changed: 44 additions & 0 deletions

File tree

‎langfuse/_client/client.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,8 @@ class Langfuse:
219219
220220
Return `None` to leave the batch unchanged. Return `MaskOtelSpansResult` with `OtelSpanPatch` values to delete or replace attributes on selected spans. If a batch contains duplicate trace and span identifiers, Langfuse keeps only the last matching span. If the hook raises or returns an invalid batch result, Langfuse drops the whole export batch. If one returned span patch is invalid, Langfuse drops only that span from the Langfuse export.
221221
222+
Values of `langfuse.trace.metadata.*` and `langfuse.observation.metadata.*` attributes written by the SDK are JSON-encoded strings, including on third-party instrumentation spans such as OpenInference (`acme` arrives as `'"acme"'`). Decode them with `json.loads` before applying masking rules and encode replacements with `json.dumps`, for example `OtelSpanPatch(set_attributes={key: json.dumps("[REDACTED]")})`. Values from other sources, such as baggage from an older upstream service, can be raw strings, so catch `json.JSONDecodeError` rather than letting the hook raise. See `MaskOtelSpansFunction` for a full example.
223+
222224
Example:
223225
```python
224226
from typing import Optional

‎langfuse/types.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,48 @@ def mask_otel_spans(
277277
278278
langfuse = Langfuse(mask_otel_spans=mask_otel_spans)
279279
```
280+
281+
Values of `langfuse.trace.metadata.*` and `langfuse.observation.metadata.*`
282+
attributes written by the SDK are JSON-encoded strings. This includes spans
283+
from third-party instrumentations such as OpenInference, because propagated
284+
metadata is copied onto them. A string value `acme` arrives as `'"acme"'`
285+
and the number `3` as `'3'`. Decode each value with `json.loads` before
286+
applying masking rules, and encode replacements with `json.dumps`. Values
287+
that reach a span another way, such as baggage from an older or
288+
non-Langfuse upstream service, can be raw strings. Guard the decode,
289+
because an exception from the hook drops the whole export batch:
290+
291+
```python
292+
import json
293+
294+
METADATA_PREFIXES = (
295+
"langfuse.trace.metadata.",
296+
"langfuse.observation.metadata.",
297+
)
298+
299+
def mask_otel_spans(
300+
*, params: MaskOtelSpansParams
301+
) -> Optional[MaskOtelSpansResult]:
302+
patches = {}
303+
304+
for identifier, span in params.spans.items():
305+
updates = {}
306+
for key, value in span.attributes.items():
307+
if not key.startswith(METADATA_PREFIXES):
308+
continue
309+
if not isinstance(value, str):
310+
continue
311+
try:
312+
decoded = json.loads(value)
313+
except json.JSONDecodeError:
314+
decoded = value
315+
if decoded == "acme":
316+
updates[key] = json.dumps("[REDACTED]")
317+
if updates:
318+
patches[identifier] = OtelSpanPatch(set_attributes=updates)
319+
320+
return MaskOtelSpansResult(span_patches=patches)
321+
```
280322
"""
281323

282324
def __call__(

0 commit comments

Comments
 (0)