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.

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

The v3 SDK is currently in beta. Please check out the SDK v3 for more details.

from langfuse import Langfuse, observe
 
# Either set the environment variable or the constructor parameter. The latter takes precedence.
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
 
# Configure the client
langfuse = Langfuse(environment="production")
 
# All operations will now be associated with the "production" environment
with langfuse.start_as_current_span(name="my-operation") as span:
    # Your code here
    pass
 
@observe
def main():
    return "Hello"
 
main()

When using the @observe() decorator:

from langfuse.decorators import langfuse_context, observe
 
# Either set the environment variable or configure the decorator. The latter takes precedence.
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
 
# Configure the decorator
langfuse_context.configure(environment="production")
 
@observe()
def fn():
    pass
 
fn()

When using the low-level SDK:

from langfuse import Langfuse
 
# Either set the environment variable or the constructor parameter. The latter takes precedence.
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
 
# Configure the client
langfuse = Langfuse(environment="production")
 
trace = langfuse.trace(
  name="Rap Battle",
)

import { Langfuse } from "langfuse";
 
const langfuse = new Langfuse({
  environment: "production",
});

See JS/TS SDK docs for more details.

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_span("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 v3, 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 v3 tab for more details.

When using the OpenAI SDK Integration

Python SDK v3:

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 = "}],
)

Python SDK v2:

from langfuse.openai import openai
 
# Either set the environment variable or configure the openai import. The latter takes precedence.
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
 
# Configure the openai import
openai.langfuse_environment = "production"
 
completion = openai.chat.completions.create(
  name="test-chat",
  model="gpt-3.5-turbo",
  messages=[
    {"role": "system", "content": "You are a calculator."},
    {"role": "user", "content": "1 + 1 = "}],
)

import OpenAI from "openai";
import { observeOpenAI } from "langfuse";
 
const openai = observeOpenAI(new OpenAI(), {
  clientInitParams: {
    environment: "production",
  },
});

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

When using the Python SDK v3, 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 v3 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(
  environment="production"
)

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 { LangfuseExporter } from "langfuse-vercel";
 
export function register() {
  registerOTel({
    serviceName: "langfuse-vercel-ai-nextjs-example",
    traceExporter: new LangfuseExporter({ environment: "production" }),
  });
}

The LlamaIndex integration is not supported in the Python SDK v3. Please use a community-maintained OTEL-based integration instead.

When using the LlamaIndex Integration

import os
from langfuse.llama_index import LlamaIndexInstrumentor
 
# Either set the environment variable or the constructor parameter. The latter takes precedence.
os.environ["LANGFUSE_TRACING_ENVIRONMENT"] = "production"
instrumentor = LlamaIndexInstrumentor(environment="production")

Filtering

In the Langfuse UI, you can filter events by environment using the environment filter in the navigation bar. This filter applies across all views in Langfuse.

See our API Reference for details on how to filter by environment on our API.

Best Practices

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.

Environments

Data Model

Usage

Filtering

Best Practices

GitHub Discussions

Was this page useful?

Questions? We're here to help

Subscribe to updates