Environments

Environments allow you to keep traces from different deployment contexts — production, staging, development — in the same XeroML project while keeping them cleanly separated. You can filter the entire dashboard by environment, so your production data is never mixed with test data.

Setting the Environment

The recommended approach is to use the XEROML_TRACING_ENVIRONMENT environment variable. XeroML reads it automatically on startup.

# In your deployment environment
XEROML_TRACING_ENVIRONMENT=production

# In your staging environment
XEROML_TRACING_ENVIRONMENT=staging

# In local development
XEROML_TRACING_ENVIRONMENT=development

You can also set it in code during client initialization, which takes precedence over the environment variable:

import os
from xeroml import get_client

# Via environment variable (recommended)
os.environ["XEROML_TRACING_ENVIRONMENT"] = "production"
xeroml = get_client()

import { XeroMLSpanProcessor } from "@xeroml/otel";

const processor = new XeroMLSpanProcessor({
  environment: "production",
});

Set as a resource attribute or span attribute:

# Via OTEL_RESOURCE_ATTRIBUTES
OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production"

# Or programmatically per-span
span.set_attribute("xeroml.environment", "production")

If no environment is set, the default is default.

Naming Requirements

Environment names must match ^(?!xeroml)[a-z0-9-_]+$ and be no longer than 40 characters.

✅ production, staging, dev, feature-branch-123
❌ xeroml-prod (cannot start with “xeroml”)
❌ Production (no uppercase)
❌ my environment (no spaces)

What Gets Tagged

The environment attribute applies to all XeroML events:

Traces
All observation types (spans, generations, events)
Scores
Sessions

UI Filtering

Once environments are configured, a dropdown in the XeroML navigation bar lets you filter all views — Traces, Sessions, Users, Prompts — by environment. Environments are created automatically on first use and persist indefinitely.