# Source: https://langfuse.com/docs/observability/sdk/advanced-features.md

---
title: Advanced features of the Langfuse SDKs
description: Configure masking, logging, sampling, multi-project routing, evaluations, and environment-specific behaviors for Python and JS/TS.
category: SDKs
---

# Advanced features

Use these methods to harden your Langfuse instrumentation, protect sensitive data, and adapt the SDKs to your specific environment.

## Filtering by Instrumentation Scope [#filtering-by-instrumentation-scope]

You can configure the SDK to filter out spans from specific instrumentation libraries that expose OTel spans that the Langfuse SDK picks up but you don't want to send to Langfuse.

**How it works:**

When third-party libraries create OpenTelemetry spans (through their instrumentation packages), each span has an associated "instrumentation scope" that identifies which library created it. The Langfuse SDK filters spans at the export level based on these scope names.

You can see the instrumentation scope name for any span in the Langfuse UI under the observation's metadata (`metadata.scope.name`). Use this to identify which scopes you want to filter.

<Callout type="warning" title="Filtering Spans May Break Trace Trees">
  **Cross-Library Span Relationships:**
  Filtering spans may break the parent-child relationships in your traces. For
  example, if you filter out a parent span but keep its children, you may see
  "orphaned" observations in the Langfuse UI.
</Callout>

<LangTabs items={["Python SDK", "JS/TS SDK"]}>
<Tab title="Python SDK">

Provide the `blocked_instrumentation_scopes` parameter to the `Langfuse` client to filter out spans from specific instrumentation libraries.

```python
from langfuse import Langfuse

# Filter out database spans
langfuse = Langfuse(
    blocked_instrumentation_scopes=["sqlalchemy", "psycopg"]
)
```

</Tab>
<Tab title="JS/TS SDK">

You can provide a predicate function `shouldExportSpan` to the `LangfuseSpanProcessor` to decide on a per-span basis whether it should be exported to Langfuse.

```ts filename="instrumentation.ts" /shouldExportSpan/
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor, ShouldExportSpan } from "@langfuse/otel";

// Example: Filter out all spans from the 'express' instrumentation
const shouldExportSpan: ShouldExportSpan = ({ otelSpan }) =>
  otelSpan.instrumentationScope.name !== "express";

const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor({ shouldExportSpan })],
});

sdk.start();
```

If you want to include only LLM observability related spans, you can configure an allowlist like so:

```ts filename="instrumentation.ts"
import { ShouldExportSpan } from "@langfuse/otel";

const shouldExportSpan: ShouldExportSpan = ({ otelSpan }) =>
  ["langfuse-sdk", "ai"].includes(otelSpan.instrumentationScope.name);
```

</Tab>
</LangTabs>

You can read more about using Langfuse with an existing OpenTelemetry setup [here](/faq/all/existing-otel-setup).

## Mask sensitive data

If your trace data (inputs, outputs, metadata) might contain sensitive information (PII, secrets), you can provide a mask function during client initialization. This function will be applied to all relevant data before it’s sent to Langfuse.

<LangTabs items={["Python SDK", "JS/TS SDK"]}>
<Tab title="Python SDK">

The `mask` function should accept data as a keyword argument and return the masked data. The returned data must be JSON-serializable.


```python
from langfuse import Langfuse
import re

def pii_masker(data: any, **kwargs) -> any:
    if isinstance(data, str):
        return re.sub(r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+", "[EMAIL_REDACTED]", data)
    elif isinstance(data, dict):
        return {k: pii_masker(data=v) for k, v in data.items()}
    elif isinstance(data, list):
        return [pii_masker(data=item) for item in data]
    return data

langfuse = Langfuse(mask=pii_masker)
```
</Tab>
<Tab title="JS/TS SDK">

You can provide a `mask` function to the [`LangfuseSpanProcessor`](https://langfuse-js-git-main-langfuse.vercel.app/classes/_langfuse_otel.LangfuseSpanProcessor.html). This function will be applied to the input, output, and metadata of every observation.

The function receives an object `{ data }`, where `data` is the stringified JSON of the attribute's value. It should return the masked data.

```ts filename="instrumentation.ts" /mask: /
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const spanProcessor = new LangfuseSpanProcessor({
  mask: ({ data }) =>
    data.replace(/\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g, "***MASKED_CREDIT_CARD***"),
});

const sdk = new NodeSDK({ spanProcessors: [spanProcessor] });

sdk.start();
```
</Tab>
</LangTabs>

## Logging & debugging

The Langfuse SDK can expose detailed logging and debugging information to help you troubleshoot issues with your application.

<LangTabs items={["Python SDK", "JS/TS SDK"]}>
<Tab title="Python SDK">

**In code:**

The Langfuse SDK uses Python's standard `logging` module. The main logger is named `"langfuse"`.
To enable detailed debug logging, you can either:

1.  Set the `debug=True` parameter when initializing the `Langfuse` client.
2.  Configure the `"langfuse"` logger manually:

```python
import logging

langfuse_logger = logging.getLogger("langfuse")
langfuse_logger.setLevel(logging.DEBUG)
```

The default log level for the `langfuse` logger is `logging.WARNING`.

**Via environment variable:**

You can also set the log level using the `LANGFUSE_DEBUG` environment variable to enable the debug mode.

```bash
export LANGFUSE_DEBUG="True"
```

</Tab>
<Tab title="JS/TS SDK">

You can configure the global SDK logger to control the verbosity of log output. This is useful for debugging.

**In code:**

```typescript /configureGlobalLogger/
import { configureGlobalLogger, LogLevel } from "@langfuse/core";

// Set the log level to DEBUG to see all log messages
configureGlobalLogger({ level: LogLevel.DEBUG });
```

Available log levels are `DEBUG`, `INFO`, `WARN`, and `ERROR`.

**Via environment variable:**

You can also set the log level using the `LANGFUSE_LOG_LEVEL` environment variable to enable the debug mode.

```bash
export LANGFUSE_LOG_LEVEL="DEBUG"
```

</Tab>
</LangTabs>

## Sampling

Sampling lets send only a subset of traces to Langfuse. This is useful to reduce costs and noise in high-volume applications.

<LangTabs items={["Python SDK", "JS/TS SDK"]}>
<Tab title="Python SDK">

**In code:**

You can configure the SDK to sample traces by setting the `sample_rate` parameter during client initialization. This value should be a float between `0.0` (sample 0% of traces) and `1.0` (sample 100% of traces).

If a trace is not sampled, none of its observations (spans, generations) or associated scores will be sent to Langfuse.

```python
from langfuse import Langfuse

# Sample approximately 20% of traces
langfuse_sampled = Langfuse(sample_rate=0.2)
```

**Via environment variable:**

You can also set the sample rate using the `LANGFUSE_SAMPLE_RATE` environment variable.

```bash
export LANGFUSE_SAMPLE_RATE="0.2"
```


</Tab>
<Tab title="JS/TS SDK">

**In code:**

Langfuse respects OpenTelemetry's sampling decisions. Configure a sampler on your OTEL `NodeSDK` to control which traces reach Langfuse and reduce noise/costs in high-volume workloads.

```ts filename="instrumentation.ts" /TraceIdRatioBasedSampler/
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

const sdk = new NodeSDK({
  sampler: new TraceIdRatioBasedSampler(0.2),
  spanProcessors: [new LangfuseSpanProcessor()],
});

sdk.start();
```

**Via environment variable:**

You can also set the sample rate using the `LANGFUSE_SAMPLE_RATE` environment variable.

```bash
export LANGFUSE_SAMPLE_RATE="0.2"
```

</Tab>
</LangTabs>

## Isolated TracerProvider [#isolated-tracer-provider]

You can configure a separate OpenTelemetry TracerProvider for use with Langfuse. This creates isolation between Langfuse tracing and your other observability systems.

Benefits of isolation:

- Langfuse spans won't be sent to your other observability backends (e.g., Datadog, Jaeger, Zipkin)
- Third-party library spans won't be sent to Langfuse
- Independent configuration and sampling rates

<Callout type="warning">
While TracerProviders are isolated, they share the same OpenTelemetry context for tracking active spans. This can cause span relationship issues where: 

- A parent span from one TracerProvider might have children from another TracerProvider 
- Some spans may appear "orphaned" if their parent spans belong to a different TracerProvider 
- Trace hierarchies may be incomplete or confusing

Plan your instrumentation carefully to avoid confusing trace structures.
</Callout>


<LangTabs items={["Python SDK", "JS/TS SDK"]}>
<Tab title="Python SDK">

```python {4, 5}
from opentelemetry.sdk.trace import TracerProvider
from langfuse import Langfuse
 
langfuse_tracer_provider = TracerProvider() # do not set to global tracer provider to keep isolation
langfuse = Langfuse(tracer_provider=langfuse_tracer_provider)
langfuse.start_span(name="myspan").end() # Span will be isolated from remaining OTEL instrumentation
```

</Tab>
<Tab title="JS/TS SDK">
Isolate Langfuse spans with a custom provider and avoid sending them to other exporters.

```ts /setLangfuseTracerProvider/
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { setLangfuseTracerProvider } from "@langfuse/tracing";
 
// Create a new TracerProvider and register the LangfuseSpanProcessor
// do not set this TracerProvider as the global TracerProvider
const langfuseTracerProvider = new NodeTracerProvider({
  spanProcessors: [new LangfuseSpanProcessor()],
})
 
// Register the isolated TracerProvider
setLangfuseTracerProvider(langfuseTracerProvider)
```

</Tab>
</LangTabs>

You can read more about using Langfuse with an existing OpenTelemetry setup [here](/faq/all/existing-otel-setup).

## Multi-project setups [#multi-project-setup-experimental]

<LangTabs items={["Python SDK", "JS/TS SDK"]}>
<Tab title="Python SDK">

<Callout type="warning">
Multi-project setups are **experimental** in the Python SDK and have important limitations regarding third-party OpenTelemetry integrations.
</Callout>

The Langfuse Python SDK supports routing traces to different projects within the same application by using multiple public keys. This works because the Langfuse SDK adds a specific span attribute containing the public key to all spans it generates.

**How it works:**

1. **Span Attributes**: The Langfuse SDK adds a specific span attribute containing the public key to spans it creates
2. **Multiple Processors**: Multiple span processors are registered onto the global tracer provider, each with their respective exporters bound to a specific public key
3. **Filtering**: Within each span processor, spans are filtered based on the presence and value of the public key attribute

**Important Limitation with Third-Party Libraries:**

Third-party libraries that emit OpenTelemetry spans automatically (e.g., HTTP clients, databases, other instrumentation libraries) do **not** have the Langfuse public key span attribute. As a result:

- These spans cannot be routed to a specific project
- They are processed by all span processors and sent to all projects
- All projects will receive these third-party spans

**Why is this experimental?**
This approach requires that the `public_key` parameter be passed to all Langfuse SDK executions across all integrations to ensure proper routing, and third-party spans will appear in all projects.

### Initialization

To set up multiple projects, initialize separate Langfuse clients for each project:

```python
from langfuse import Langfuse

# Initialize clients for different projects
project_a_client = Langfuse(
    public_key="pk-lf-project-a-...",
    secret_key="sk-lf-project-a-...",
    base_url="https://cloud.langfuse.com"
)

project_b_client = Langfuse(
    public_key="pk-lf-project-b-...",
    secret_key="sk-lf-project-b-...",
    base_url="https://cloud.langfuse.com"
)
```

### Integration Usage

For all integrations in multi-project setups, you must specify the `public_key` parameter to ensure traces are routed to the correct project.

**Observe Decorator:**

Pass `langfuse_public_key` as a keyword argument to the *top-most* observed function (not the decorator). From Python SDK >= 3.2.2, nested decorated functions will automatically pick up the public key from the execution context they are currently into. Also, calls to `get_client` will be also aware of the current `langfuse_public_key` in the decorated function execution context, so passing the `langfuse_public_key` here again is not necessary.

```python
from langfuse import observe

@observe
def nested():
    # get_client call is context aware
    # if it runs inside another decorated function that has
    # langfuse_public_key passed, it does not need passing here again


@observe
def process_data_for_project_a(data):
    # passing `langfuse_public_key` here again is not necessarily
    # as it is stored in execution context
    nested()

    return {"processed": data}

@observe
def process_data_for_project_b(data):
    # passing `langfuse_public_key` here again is not necessarily
    # as it is stored in execution context
    nested()

    return {"enhanced": data}

# Route to Project A
# Top-most decorated function needs `langfuse_public_key` kwarg
result_a = process_data_for_project_a(
    data="input data",
    langfuse_public_key="pk-lf-project-a-..."
)

# Route to Project B
# Top-most decorated function needs `langfuse_public_key` kwarg
result_b = process_data_for_project_b(
    data="input data",
    langfuse_public_key="pk-lf-project-b-..."
)
```

**OpenAI Integration:**

Add `langfuse_public_key` as a keyword argument to the OpenAI execution:

```python
from langfuse.openai import openai

client = openai.OpenAI()

# Route to Project A
response_a = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello from Project A"}],
    langfuse_public_key="pk-lf-project-a-..."
)

# Route to Project B
response_b = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello from Project B"}],
    langfuse_public_key="pk-lf-project-b-..."
)
```

**Langchain Integration:**

Add `public_key` to the CallbackHandler constructor:

```python
from langfuse.langchain import CallbackHandler
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Create handlers for different projects
handler_a = CallbackHandler(public_key="pk-lf-project-a-...")
handler_b = CallbackHandler(public_key="pk-lf-project-b-...")

llm = ChatOpenAI(model_name="gpt-4o")
prompt = ChatPromptTemplate.from_template("Tell me about {topic}")
chain = prompt | llm

# Route to Project A
response_a = chain.invoke(
    {"topic": "machine learning"},
    config={"callbacks": [handler_a]}
)

# Route to Project B
response_b = chain.invoke(
    {"topic": "data science"},
    config={"callbacks": [handler_b]}
)
```

**Important Considerations:**

- Every Langfuse SDK execution across all integrations must include the appropriate public key parameter
- Missing public key parameters may result in traces being routed to the default project or lost
- Third-party OpenTelemetry spans (from HTTP clients, databases, etc.) will appear in all projects since they lack the Langfuse public key attribute

</Tab>


<Tab title="JS/TS SDK">

You can configure the SDK to send traces to multiple Langfuse projects. This is useful for multi-tenant applications or for sending traces to different environments. Simply register multiple `LangfuseSpanProcessor` instances, each with its own credentials.

```ts filename="instrumentation.ts"
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const sdk = new NodeSDK({
  spanProcessors: [
    new LangfuseSpanProcessor({
      publicKey: "pk-lf-public-key-project-1",
      secretKey: "sk-lf-secret-key-project-1",
    }),
    new LangfuseSpanProcessor({
      publicKey: "pk-lf-public-key-project-2",
      secretKey: "sk-lf-secret-key-project-2",
    }),
  ],
});

sdk.start();
```

This configuration will send every trace to both projects. You can also configure a custom `shouldExportSpan` filter for each processor to control which traces go to which project.


</Tab>
</LangTabs>

## Time to first token (TTFT)

You can manually set the time to first token (TTFT) of your LLM calls. This is useful for measuring the latency of your LLM calls and for identifying slow LLM calls.

<LangTabs items={["Python SDK", "JS/TS SDK"]}>
<Tab title="Python">

You can use the `completion_start_time` attribute to manually set the time to first token (TTFT) of your LLM calls. This is useful for measuring the latency of your LLM calls and for identifying slow LLM calls.

```python
from langfuse import get_client
import datetime, time

langfuse = get_client()

with langfuse.start_as_current_observation(as_type="generation", name="TTFT-Generation") as generation:
    time.sleep(3)
    generation.update(
        completion_start_time=datetime.datetime.now(),
        output="some response",
    )

langfuse.flush()
```

</Tab>
<Tab title="JS/TS SDK">

You can use the `completionStartTime` attribute to manually set the time to first token (TTFT) of your LLM calls. This is useful for measuring the latency of your LLM calls and for identifying slow LLM calls.

```ts
import { startActiveObservation } from "@langfuse/tracing";

startActiveObservation("llm-call", async (span) => {
  span.update({
    completionStartTime: new Date().toISOString(),
  });
});
```

</Tab>
</LangTabs>

## Self-signed SSL certificates (self-hosted Langfuse)

If you are [self-hosting](/docs/deployment/self-host) Langfuse and you'd like to use self-signed SSL certificates, you will need to configure the SDK to trust the self-signed certificate:

<Callout type='warning'>
Changing SSL settings has major security implications depending on your environment. Be sure you understand these implications before you proceed.
</Callout>

**1. Set OpenTelemetry span exporter to trust self-signed certificate**

```bash filename=".env"
OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE="/path/to/my-selfsigned-cert.crt"
```

**2. Set HTTPX to trust certificate for all other API requests to Langfuse instance**

```python filename="main.py"
import os

import httpx

from langfuse import Langfuse

httpx_client = httpx.Client(verify=os.environ["OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE"])

langfuse = Langfuse(httpx_client=httpx_client)
```

## Setup with Sentry

If you’re using both Sentry and Langfuse in your application, you’ll need to configure a custom OpenTelemetry setup since both tools use OpenTelemetry for tracing. [This guide shows how to send error monitoring data to Sentry while simultaneously capturing LLM observability traces in Langfuse](/faq/all/existing-sentry-setup).

## Thread pools and multiprocessing

<LangTabs items={["Python SDK"]}>
<Tab title="Python">

Use the OpenTelemetry threading instrumentor so context flows across worker threads.

```python
from opentelemetry.instrumentation.threading import ThreadingInstrumentor

ThreadingInstrumentor().instrument()
```

For multiprocessing, follow the [OpenTelemetry guidance](https://github.com/open-telemetry/opentelemetry-python/issues/2765#issuecomment-1158402076). If you use Pydantic Logfire, enable `distributed_tracing=True`.

</Tab>
</LangTabs>