Organizing Data by Environment

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 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:

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"]

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

Get Started

How To

Debug & Improve AI Performance

Understand Data Impact

Collaborate with Your Team

Deploy & Manage

Integrations

Learn

Resources

Why Use Environments?

Setting the Environment

Common Environment Names

Environment from Environment Variables

Multiple Environments in One Project

Separate Projects vs Environments

Option 1: One Project, Multiple Environments (Recommended)

Option 2: Separate Projects per Environment

Querying by Environment

Best Practices

Always Tag Production

Use Consistent Names

Document Your Environment Strategy

Next Steps

View Traces

Projects

Create Collections

Troubleshooting

​Why Use Environments?

​Setting the Environment

​Common Environment Names

​Environment from Environment Variables

​Multiple Environments in One Project

​Separate Projects vs Environments

​Option 1: One Project, Multiple Environments (Recommended)

​Option 2: Separate Projects per Environment

​Querying by Environment

​Best Practices

​Always Tag Production

​Use Consistent Names

​Document Your Environment Strategy

​Next Steps

View Traces

Projects

Create Collections

Troubleshooting

Why Use Environments?

Setting the Environment

Common Environment Names

Environment from Environment Variables

Multiple Environments in One Project

Separate Projects vs Environments

Option 1: One Project, Multiple Environments (Recommended)

Option 2: Separate Projects per Environment

Querying by Environment

Best Practices

Always Tag Production

Use Consistent Names

Document Your Environment Strategy

Next Steps