Tagging traces with environments helps you organize and analyze traces from different stages of your deployment pipeline. This makes it easy to debug production issues without sifting through development traces.
Why Use Environments?
Separating traces by environment allows you to:
- Debug production issues without dev/test traces cluttering the view
- Compare performance between environments (e.g., staging vs production)
- Track costs separately for each environment
- Monitor quality at different stages of deployment
- Test changes in staging before deploying to production
Setting the Environment
Tag traces by passing the environment parameter when initializing the connector:
from arcbeam_connector.langchain.connector import ArcbeamLangConnector
connector = ArcbeamLangConnector(
base_url="http://platform.arcbeam.ai",
api_key="your-api-key-here",
environment="production", # Tag all traces with this environment
)
connector.init()
Common Environment Names
While you can use any string for the environment, these are common conventions:
| Environment | Description | Use Case |
|---|
dev or development | Local development | Testing features locally |
staging | Pre-production testing | QA and integration testing |
production or prod | Live production | Real user traffic |
test | Automated testing | CI/CD pipelines |
Use consistent naming across your organization. Decide on prod vs production and stick with it.
Environment from Environment Variables
The best practice is to set the environment using the ARCBEAM_ENVIRONMENT environment variable:
# Local development
export ARCBEAM_ENVIRONMENT=dev
python app.py
# Staging
export ARCBEAM_ENVIRONMENT=staging
python app.py
# Production
export ARCBEAM_ENVIRONMENT=production
python app.py
Multiple Environments in One Project
You can send traces from multiple environments to the same project. Each trace is tagged with its environment, so you can easily filter between them.
Example setup:
- Project: “Customer Support Bot”
- Environments:
dev - Your local machinestaging - Staging serverproduction - Live production server
All traces go to the same project, but you can filter to see only production traces when debugging issues.
Separate Projects vs Environments
You have two options for organizing traces:
| Feature | One Project, Multiple Environments (Recommended) | Separate Projects per Environment |
|---|
| Setup Complexity | Simple - one project ID to manage | More complex - multiple project IDs to manage |
| Comparing Environments | Easy - all traces in one place | Harder - need to switch between projects |
| Data Separation | Mixed together (filterable by environment tag) | Complete separation |
| Permissions Management | Same permissions for all environments | Can set different permissions per environment |
| Cost Tracking | Manual filtering required | Cleaner separation by project |
| Use Case | Best for most teams, especially smaller projects | Best for large teams with strict environment isolation |
Option 1: One Project, Multiple Environments (Recommended)
# All environments use the same project
connector = ArcbeamLangConnector(
base_url="http://platform.arcbeam.ai",
api_key="your-api-key-here",
project_id="f60a7195-665f-4014-8bb3-805ae4337aa9", # UUID
environment=os.environ.get("ARCBEAM_ENVIRONMENT"), # dev, staging, or production
)
Option 2: Separate Projects per Environment
import os
# Different project UUIDs for each environment
project_ids = {
"dev": "a1b2c3d4-e5f6-4a5b-8c7d-9e0f1a2b3c4d",
"staging": "b2c3d4e5-f6a7-5b6c-9d8e-0f1a2b3c4d5e",
"production": "c3d4e5f6-a7b8-6c7d-0e9f-1a2b3c4d5e6f",
}
env = os.environ.get("ARCBEAM_ENVIRONMENT", "dev")
project_id = project_ids[env]
connector = ArcbeamLangConnector(
base_url="http://platform.arcbeam.ai",
api_key="your-api-key-here",
project_id=project_id,
)
Most teams prefer Option 1 (one project, multiple environments) because it’s simpler and makes comparisons easier.
Querying by Environment
You can query traces by environment using the Arcbeam API:
import requests
response = requests.get(
"http://platform.arcbeam.ai/api/v0/traces",
params={
"environment": "production", # Filter by environment
"from_date": "2025-12-01T00:00:00Z",
"to_date": "2025-12-31T23:59:59Z",
},
headers={"arcbeam-api-key": "your-api-key-here"}
)
traces = response.json()["traces"]
- Custom dashboards
- Automated alerts
- Cost reporting by environment
Best Practices
Always Tag Production
At minimum, always tag production traces:
import os
# Explicitly tag production
env = os.environ.get("ARCBEAM_ENVIRONMENT", "dev")
connector = ArcbeamLangConnector(
base_url="http://platform.arcbeam.ai",
api_key=os.environ.get("ARCBEAM_API_KEY"),
environment=env,
)
Use Consistent Names
Pick environment names and stick with them:
# Good: Consistent naming
VALID_ENVIRONMENTS = ["dev", "staging", "production"]
environment = os.environ.get("ARCBEAM_ENVIRONMENT", "dev")
assert environment in VALID_ENVIRONMENTS, f"Invalid environment: {environment}"
"producton" or "prod" vs "production".
Document Your Environment Strategy
Make it clear in your team’s docs:
- Which environments exist
- What each environment is for
- How to tag traces correctly
Next Steps
