Environments — separate production, staging, and development data

Zespan gives you two ways to separate data from different environments: the environment tag and separate projects. Understanding when to use each — and how they interact — saves you from mixing staging noise into production dashboards or accidentally billing production usage against a test quota.

This guide covers the strategic choice between environment tagging and separate projects. For the environment switcher, the settings page, the seeded dev/staging/prod defaults, and exactly how a free-text SDK value like "production" resolves against them, see Environments.

The `environment` tag

Every event sent by the SDK carries an environment string. It defaults to "production" but you should always set it explicitly from your deployment configuration:

TypeScript
Python

zespan.init({
  apiKey: process.env.ZESPAN_API_KEY!,
  environment: process.env.NODE_ENV === "production" ? "production" : "staging",
});

import os
import zespan

zespan.init(
    api_key=os.environ["ZESPAN_API_KEY"],
    environment=os.getenv("ENVIRONMENT", "development"),
)

The environment string is free-form — you can use "production", "staging", "development", "canary", "load-test", or any value that makes sense for your deploy pipeline. Every project is seeded with three environment records — dev, staging, prod — and "production"/"development" automatically alias onto prod/dev, so the values shown in the example above line up with the dashboard’s defaults with no extra configuration. A value that matches neither a seeded slug nor an alias (e.g. "canary") is still accepted and stored as-is — create a matching environment in Settings → Environments if you want it to resolve as a known environment rather than a flagged one.

Filtering by environment in the dashboard

An environment switcher in the project header lets you scope any page — Traces, Evaluations, Guardrails, Incidents, metrics — to one environment at a time. It defaults to All environments; pick one to narrow the view. See Environments for the full reference, including the environment API query parameter and how it interacts with historical free-text data.

When you’re debugging a new feature, set environment: "development" locally. This keeps your development noise out of the production Cost page and anomaly detector, which both operate on the production (aliased to prod) environment by default.

One project vs. multiple projects

The environment tag filters data within a project. The alternative is separate projects — one per environment. Here’s how to choose:

Approach	Best for	Tradeoffs
Single project + environment tag	Most teams	Simpler setup, one API key, shared alert rules and evaluators
Separate project per environment	Strict data isolation, different retention policies per env	Multiple API keys to manage, alert rules duplicated across projects
Separate project for load testing	High-volume synthetic traffic	Keeps load-test events from inflating your monthly quota

When to use separate projects

Use a separate project when you need:

Different data retention — keep staging data for 7 days while production data is kept for 90 days
Separate billing — different teams own different projects and need separate usage reporting
True data isolation — environment tag filtering is UI-only; both environments still share the same project quota
Load testing — synthetic traffic inflates your monthly event quota and skews your anomaly baselines

When to stay in one project

Use environment tags (single project) when:

Your team is small and shares a single dashboard
You want alert rules, guardrails, and evaluators to automatically apply to all environments
You’re on the Free or Pro plan and don’t want to manage multiple API keys

Recommended setup for most teams

Organization: AcmeCorp
├── Project: acme-production   (API key: zsp_prod_...)
│   └── environment: "production"
│
└── Project: acme-staging      (API key: zsp_staging_...)
    └── environment: "staging"

Each project gets its own API key. Set the key from environment variables — never hardcode:

# .env.production
ZESPAN_API_KEY=zsp_prod_xxxxxxxxxxxxxxxxxx
ZESPAN_ENV=production

# .env.staging
ZESPAN_API_KEY=zsp_staging_xxxxxxxxxxxxxxxxxx
ZESPAN_ENV=staging

zespan.init({
  apiKey: process.env.ZESPAN_API_KEY!,
  environment: process.env.ZESPAN_ENV ?? "development",
});

Keeping local development clean

By default the SDK sends events even in local development. This is useful for debugging but can pollute your dashboard. Two options: Option 1 — Disable in development:

zespan.init({
  apiKey: process.env.ZESPAN_API_KEY ?? "zsp_local",
  environment: "development",
  // Only send if we have a real API key
  sampleRate: process.env.ZESPAN_API_KEY ? 1.0 : 0.0,
});

Option 2 — Lower sample rate for development:

const isDev = process.env.NODE_ENV === "development";

zespan.init({
  apiKey: process.env.ZESPAN_API_KEY!,
  environment: isDev ? "development" : "production",
  sampleRate: isDev ? 0.1 : 1.0, // only sample 10% in dev
});

Tagging for feature-level filtering

Beyond environments, the tags field lets you segment by feature, team, or experiment — without creating separate projects:

await withZespanContext(
  {
    userId: req.user.id,
    sessionId: req.session.id,
    tags: {
      feature: "checkout-assistant",    // which feature triggered this call
      team: "payments",                  // which team owns this code
      experiment: "gpt4o-vs-mini-ab",   // A/B experiment identifier
      release: "v2.4.1",                // deployment version
    },
  },
  async () => {
    await openai.chat.completions.create({ ... });
  }
);

You can filter and group by these tags in the Traces view, and use them in alert rule conditions to scope an alert to a specific feature.

Overview

CLI

TypeScript SDK

Python SDK

Advanced SDK Configuration

Integrations

LLM Providers

Agent Frameworks

RAG Frameworks

Gateways

Vector Databases

Custom / Other

Guides

Environments — separate production, staging, and development data

The `environment` tag

Filtering by environment in the dashboard

One project vs. multiple projects

When to use separate projects

When to stay in one project

Recommended setup for most teams

Keeping local development clean

Tagging for feature-level filtering

​The environment tag

​Filtering by environment in the dashboard

​One project vs. multiple projects

​When to use separate projects

​When to stay in one project

​Recommended setup for most teams

​Keeping local development clean

​Tagging for feature-level filtering

The `environment` tag

Filtering by environment in the dashboard

One project vs. multiple projects

When to use separate projects

When to stay in one project

Recommended setup for most teams

Keeping local development clean

Tagging for feature-level filtering