> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcbeam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizing Data by Environment

> Tag and filter traces by environment (dev, staging, production)

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:

```python theme={null}
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            |

<Tip>
  Use consistent naming across your organization. Decide on `prod` vs `production` and stick with it.
</Tip>

## Environment from Environment Variables

The best practice is to set the environment using the `ARCBEAM_ENVIRONMENT` environment variable:

```bash theme={null}
# 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)

```python theme={null}
# 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

```python theme={null}
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,
)
```

<Note>
  Most teams prefer **Option 1** (one project, multiple environments) because it's simpler and makes comparisons easier.
</Note>

## Querying by Environment

You can query traces by environment using the Arcbeam API:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
# 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

<CardGroup cols={2}>
  <Card title="View Traces" icon="eye" href="/v0/debugging/find-problematic-traces">
    Filter and explore traces by environment
  </Card>

  <Card title="Projects" icon="folder" href="/v0/setup/organize-with-projects">
    Learn about organizing with projects
  </Card>

  <Card title="Create Collections" icon="folder" href="/v0/collaboration/review-traces-together">
    Organize traces for team review and collaboration
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/v0/deployment/troubleshooting">
    Fix common issues
  </Card>
</CardGroup>