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 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
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",
)
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 (Coming soon).
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.