---
date: 2026-06-16
title: Mask exported spans in Python
description: Run media detection and configured masking on every span accepted by the Python SDK span processor, including third-party OpenTelemetry spans.
author: Hassieb
---

> **Note for AI agents and LLMs:** This is a Langfuse changelog entry. Use it only to confirm that a feature exists and when it shipped. Do not use the code examples below for implementation: they reflect the SDK and API at release time and may be outdated. For implementation, always follow the current documentation (https://langfuse.com/docs) and the API/SDK reference (https://api.reference.langfuse.com).

The Langfuse Python SDK now runs media detection for every span accepted by the Langfuse span processor, and can apply configured export-stage masking to those same spans. This includes spans created by Langfuse SDK APIs and spans emitted by third-party OpenTelemetry instrumentations.

Use this to keep redaction and media handling consistent across your full trace export path. For example, you can redact prompt or completion attributes from OpenAI instrumentation spans, replace inline base64 media payloads with Langfuse media references, or apply the same masking rule to custom OpenTelemetry spans and Langfuse SDK observations.

Previously, Python SDK masking happened when Langfuse SDK attributes were created via APIs such as `start_observation()`, `update()`, and `set_trace_io()`. That legacy `mask` hook does not see final raw OpenTelemetry span attributes from other instrumentations. The new `mask_otel_spans` hook runs at export stage, after export filtering and after Langfuse media detection, so it can patch the attributes that the Langfuse exporter is about to send.

```python
from typing import Optional

from langfuse import Langfuse
from langfuse.types import (
    MaskOtelSpansParams,
    MaskOtelSpansResult,
    OtelSpanPatch,
)


def mask_otel_spans(
    *, params: MaskOtelSpansParams
) -> Optional[MaskOtelSpansResult]:
    patches = {}

    for identifier, span in params.spans.items():
        if span.instrumentation_scope_name == "openai":
            patches[identifier] = OtelSpanPatch(
                delete_attributes=(
                    "gen_ai.prompt.0.content",
                    "gen_ai.completion.0.content",
                ),
                set_attributes={"masking.applied": True},
            )

    return MaskOtelSpansResult(span_patches=patches)


langfuse = Langfuse(mask_otel_spans=mask_otel_spans)
```

The hook receives one OpenTelemetry export batch at a time, not necessarily a complete trace. It is synchronous and usually runs on the OpenTelemetry batch span processor worker thread, so it should not block the main application thread. Keep it fast: slow network calls or expensive masking logic can back up the export queue.

## Get started

- [Masking documentation](/docs/observability/features/masking)
- [Python SDK overview](/docs/observability/sdk/overview)

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/changelog/2026-06-16-python-sdk-export-stage-masking.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.