Skip to main content
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:
EnvironmentDescriptionUse Case
dev or developmentLocal developmentTesting features locally
stagingPre-production testingQA and integration testing
production or prodLive productionReal user traffic
testAutomated testingCI/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 machine
    • staging - Staging server
    • production - 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:
FeatureOne Project, Multiple Environments (Recommended)Separate Projects per Environment
Setup ComplexitySimple - one project ID to manageMore complex - multiple project IDs to manage
Comparing EnvironmentsEasy - all traces in one placeHarder - need to switch between projects
Data SeparationMixed together (filterable by environment tag)Complete separation
Permissions ManagementSame permissions for all environmentsCan set different permissions per environment
Cost TrackingManual filtering requiredCleaner separation by project
Use CaseBest for most teams, especially smaller projectsBest for large teams with strict environment isolation
# 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"]
This is useful for:
  • 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,
)
This ensures you can always filter to production traces.

​
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}"
This prevents typos like "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

View Traces

Filter and explore traces by environment

Projects

Learn about organizing with projects

Create Collections

Organize traces for team review and collaboration

Troubleshooting

Fix common issues