Environments

Environments allow you to organize your traces, observations, and scores from different contexts such as production, staging, or development. This helps you:

Keep your development and production data separate while using the same project
Filter and analyze data by environment
Reuse datasets and prompts across environments

You can configure the environment by setting the LANGFUSE_TRACING_ENVIRONMENT environment variable (recommended) or by using the environment parameter in the client initialization. If both are specified, the initialization parameter takes precedence. If nothing is specified, the default environment is default.

In the Python SDK, you can also set the environment for a specific trace scope with propagate_attributes(environment="..."). This is useful when the environment belongs to the incoming request rather than to the service process itself, for example when one shared LLM proxy handles requests from development, staging, QA, and production. Use as_baggage=True to propagate that environment across service boundaries.

Data Model

The environment attribute is available on all events in Langfuse:

Traces
Observations (spans, events, generations)
Scores
Sessions

See Data Model for more details.

The environment must be a string that follows this regex pattern: ^(?!langfuse)[a-z0-9-_]+$ with at most 40 characters.

This means:

Cannot start with "langfuse"
Can only contain lowercase letters, numbers, hyphens, and underscores

Usage

from langfuse import get_client, observe, propagate_attributes
import os

# Set the environment variable
# Alternatively, set via .env file and load via dotenv
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"

# Get the client (will use environment variable)
langfuse = get_client()

# All operations will now be associated with the "production" environment
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Your code here
    pass

@observe
def main():
    return "Hello"

main()

# For request-scoped environments, propagate the environment explicitly.
# This maps to the first-class langfuse.environment field.
with langfuse.start_as_current_observation(as_type="span", name="proxy-request"):
    with propagate_attributes(environment="staging"):
        # All child observations created here are associated with staging.
        pass

Set the Langfuse Environment via environment variable:

export LANGFUSE_TRACING_ENVIRONMENT=production

When using OpenTelemetry, you can set the environment using any of these attributes:

langfuse.environment
deployment.environment.name
deployment.environment

To set an environment property globally, you can use resource attributes: os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "langfuse.environment=staging".

Alternatively, you can set the environment on a per-span basis:

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_observation("my-operation") as span:
    # Set environment using Langfuse-specific attribute
    span.set_attribute("langfuse.environment", "staging")

    # Or using OpenTelemetry convention
    span.set_attribute("deployment.environment.name", "staging")

When using the Python SDK, the environment provided on client initialization will apply to all event inputs and outputs regardless of the Langfuse-maintained integration you are using.

See the Python SDK tab for more details.

When using the OpenAI SDK Integration

from langfuse import Langfuse
from langfuse.openai import openai

# Either set the environment variable or configure the Langfuse client
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"

langfuse = Langfuse(environment="production")

# the integration will use the instantiated client under the hood
completion = openai.chat.completions.create(
  model="gpt-3.5-turbo",
  messages=[
    {"role": "system", "content": "You are a calculator."},
    {"role": "user", "content": "1 + 1 = "}],
)

.env

LANGFUSE_TRACING_ENVIRONMENT=production

import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";

const openai = observeOpenAI(new OpenAI());

See OpenAI Integration (JS/TS) for more details.

When using the Python SDK, the environment provided on client initialization will apply to all event inputs and outputs regardless of the Langfuse-maintained integration you are using.

See the Python SDK tab for more details.

from langfuse.callback import CallbackHandler

# Either set the environment variable or the constructor parameter. The latter takes precedence.
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
handler = CallbackHandler()

import { CallbackHandler } from "langfuse-langchain";

const handler = new CallbackHandler({
  environment: "production",
});

See Langchain Integration (JS/TS) for more details.

When using the Vercel AI SDK Integration

instrumentation.ts

import { registerOTel } from "@vercel/otel";
import { LangfuseSpanProcessor } from "@langfuse/otel";

export function register() {
  registerOTel({
    serviceName: "langfuse-vercel-ai-nextjs-example",
    spanProcessors: [new LangfuseSpanProcessor({ environment: "production" })],
  });
}

Consistent Environment Names: Use consistent environment names across your application to make filtering and analysis easier.
Environment-Specific Analysis: Use environments to analyze and compare metrics across different deployment stages.
Testing: Use separate environments for testing to avoid polluting production data.

GitHub Discussions

Was this page helpful?

Environments

Data Model

Usage

Filtering

Managing Environments

Best Practices

GitHub Discussions

On this page