# Source: https://langfuse.com/docs/observability/features/environments.md

---
description: Configure environments to organize your traces, observations, and scores.
sidebarTitle: Environments
---

# 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](/docs/tracing-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

<LangTabs items={["Python SDK", "JS/TS SDK", "OpenTelemetry", "OpenAI (Python)", "OpenAI (JS/TS)", "Langchain (Python)", "Langchain (JS/TS)", "Vercel AI SDK (JS/TS)"]}>
<Tab title="Python SDK">

```python
from langfuse import get_client, observe
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()
```

</Tab>
<Tab>

Set the Langfuse Environment via environment variable:

```bash
export LANGFUSE_TRACING_ENVIRONMENT=production
```

</Tab>
<Tab>

When using [OpenTelemetry](/docs/opentelemetry/get-started), 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:

```python
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")
```

</Tab>
<Tab>

<Callout type="info">

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.

</Callout>

When using the [OpenAI SDK Integration](/integrations/model-providers/openai-py)

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

</Tab>
<Tab>

```bash filename=".env"
LANGFUSE_TRACING_ENVIRONMENT=production
```

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

const openai = observeOpenAI(new OpenAI());
```

See [OpenAI Integration (JS/TS)](/integrations/model-providers/openai-js) for more details.

</Tab>

<Tab>

<Callout type="info">

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.

</Callout>

```python
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()
```

</Tab>

<Tab>

```ts
import { CallbackHandler } from "langfuse-langchain";

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

See [Langchain Integration (JS/TS)](/integrations/frameworks/langchain) for more details.

</Tab>

<Tab>

When using the [Vercel AI SDK Integration](/integrations/frameworks/vercel-ai-sdk)

```ts filename="instrumentation.ts" {/environment: "production"/}
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" }),
  });
}
```

</Tab>

</LangTabs>

## 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](/docs/api) for details on how to filter by environment on our API.

## Managing Environments

Environments are created the first time data is ingested with a given `environment` value and are persistent. They cannot currently be deleted or renamed via the UI.

For guidance on how to structure, separate, and work with multiple environments across projects and stages, see the FAQ: [Managing different environments](/faq/all/managing-different-environments).

## Best Practices

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

## GitHub Discussions

import { GhDiscussionsPreview } from "@/components/gh-discussions/GhDiscussionsPreview";

<GhDiscussionsPreview labels={["feat-tracing-environments"]} />