Multi-Environment Tracing Guide¶

Version: 1.0
Last Updated: 2026-01-13
Status: Active

Overview¶

This guide explains how to configure SwisperStudio to receive traces from multiple Swisper environments (development, staging, production) connected to a single running instance of SwisperStudio.

Architecture¶

┌─────────────────────────────────────────────────────────────────┐
│                        SwisperStudio                             │
│                  (Single Instance / Shared DB)                   │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Observability Consumer                      │   │
│  │         (Reads from Redis Stream)                        │   │
│  └─────────────────────────────────────────────────────────┘   │
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              PostgreSQL Database                         │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │   │
│  │  │   Project   │  │   Project   │  │   Project   │     │   │
│  │  │ "Swisper    │  │ "Swisper    │  │ "Swisper    │     │   │
│  │  │   DEV"      │  │   STAGING"  │  │   PROD"     │     │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘     │   │
│  │        ▲                ▲                ▲              │   │
│  │        │                │                │              │   │
│  │   Traces with      Traces with      Traces with        │   │
│  │   project_id       project_id       project_id         │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                            ▲
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  Swisper DEV    │ │ Swisper STAGING │ │ Swisper PROD    │
│                 │ │                 │ │                 │
│ Redis Stream →  │ │ Redis Stream →  │ │ Redis Stream →  │
│ project_id=     │ │ project_id=     │ │ project_id=     │
│ "dev-uuid"      │ │ "staging-uuid"  │ │ "prod-uuid"     │
└─────────────────┘ └─────────────────┘ └─────────────────┘

How Environment Differentiation Works¶

1. Project-Based Isolation¶

Each Swisper environment uses a unique project_id when sending traces. This ID is embedded in every trace event:

# In Swisper's SDK initialization (main.py)
await safe_initialize(
    redis_url=settings.SWISPER_STUDIO_REDIS_URL,
    project_id=settings.SWISPER_STUDIO_PROJECT_ID,  # <-- Unique per environment!
    stream_name=settings.SWISPER_STUDIO_STREAM_NAME,
)

2. Trace Storage¶

When SwisperStudio's observability consumer receives traces, it stores them with the project_id:

# observability_consumer.py
trace = Trace(
    id=trace_id,
    project_id=project_id,  # <-- From the SDK event
    name=data.get("name"),
    ...
)

3. Filtering in UI¶

SwisperStudio UI filters traces by project: - Each project has its own trace list - Costs are calculated per project - Analytics are separated by project

Setup Instructions¶

Step 1: Create Projects in SwisperStudio¶

Open SwisperStudio UI and create projects for each environment:

Go to Projects → Create New Project
Create projects:
Swisper Development (e.g., ID: dev-abc123-uuid)
Swisper Staging (e.g., ID: staging-xyz789-uuid)
Swisper Production (e.g., ID: prod-qrs456-uuid)
Copy the UUID for each project

Step 2: Configure Each Swisper Environment¶

Update .env in each Swisper deployment:

Development Environment¶

# .env (Swisper DEV)
SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://shared-redis:6379
SWISPER_STUDIO_PROJECT_ID=dev-abc123-uuid
SWISPER_STUDIO_STREAM_NAME=observability:events

Staging Environment¶

# .env (Swisper STAGING)
SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://shared-redis:6379
SWISPER_STUDIO_PROJECT_ID=staging-xyz789-uuid
SWISPER_STUDIO_STREAM_NAME=observability:events

Production Environment¶

# .env (Swisper PROD)
SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://shared-redis:6379
SWISPER_STUDIO_PROJECT_ID=prod-qrs456-uuid
SWISPER_STUDIO_STREAM_NAME=observability:events

Step 3: Configure SwisperStudio Consumer¶

The SwisperStudio consumer connects to the shared Redis instance:

# .env (SwisperStudio)
OBSERVABILITY_ENABLED=true
OBSERVABILITY_REDIS_URL=redis://shared-redis:6379
OBSERVABILITY_STREAM_NAME=observability:events
DEFAULT_PROJECT_ID=fallback-uuid  # Fallback if trace has no project_id

Deployment Options¶

Option A: Shared Redis (Recommended for Cloud)¶

All environments write to the same Redis stream, differentiated by project_id:

Swisper DEV    ──┐
Swisper STAGING ─┼──→  Redis Stream  ──→  SwisperStudio Consumer
Swisper PROD   ──┘     (shared)

Pros: - Single consumer to manage - Centralized trace collection - Lower infrastructure cost

Cons: - Requires network connectivity between environments - Redis must handle combined load

Option B: Separate Redis Streams Per Environment¶

Each environment has its own Redis, with separate SwisperStudio consumers:

Swisper DEV    ──→  Redis DEV    ──→  Consumer DEV   ──┐
Swisper STAGING ─→  Redis STAGING ─→  Consumer STAGING ┼─→  SwisperStudio DB
Swisper PROD   ──→  Redis PROD   ──→  Consumer PROD  ──┘

Pros: - Complete isolation - Independent scaling

Cons: - More infrastructure to manage - Multiple consumer processes

Option C: Multiple SwisperStudio Instances¶

Deploy separate SwisperStudio instances per environment (complete isolation):

Swisper DEV    ──→  SwisperStudio DEV (separate DB)
Swisper STAGING ─→  SwisperStudio STAGING (separate DB)
Swisper PROD   ──→  SwisperStudio PROD (separate DB)

Pros: - Complete data isolation - Independent deployments

Cons: - Highest infrastructure cost - No unified view across environments

Configuration Reference¶

Swisper Backend Config Fields¶

Field	Description	Example
`SWISPER_STUDIO_ENABLED`	Enable/disable tracing	`true`
`SWISPER_STUDIO_REDIS_URL`	Redis connection string	`redis://redis:6379`
`SWISPER_STUDIO_PROJECT_ID`	Unique per environment	`0d7aa606-cb29-4a31-8a59-50fa61151a32`
`SWISPER_STUDIO_STREAM_NAME`	Redis stream name	`observability:events`
`SWISPER_STUDIO_CAPTURE_REASONING`	Capture LLM thinking	`true`
`SWISPER_STUDIO_REASONING_MAX_LENGTH`	Max reasoning size	`50000`

SwisperStudio Config Fields¶

Field	Description	Example
`OBSERVABILITY_ENABLED`	Enable consumer	`true`
`OBSERVABILITY_REDIS_URL`	Redis to consume from	`redis://172.17.0.1:6379`
`OBSERVABILITY_STREAM_NAME`	Stream name	`observability:events`
`OBSERVABILITY_GROUP_NAME`	Consumer group	`swisper_studio_consumers`
`DEFAULT_PROJECT_ID`	Fallback project	`fallback-uuid`

Viewing Traces by Environment¶

In SwisperStudio UI¶

Navigate to Projects
Select the project (e.g., "Swisper Production")
View Traces tab
All traces from that environment are shown

API Filtering¶

# Get traces for production project
curl "http://swisper-studio:8001/api/v1/traces?project_id=prod-qrs456-uuid" \
  -H "Authorization: Bearer $API_KEY"

Naming Conventions¶

Recommended Project Naming¶

Environment	Project Name	Project ID Format
Development	`Swisper DEV`	`dev-{uuid}`
Staging	`Swisper STAGING`	`staging-{uuid}`
Production	`Swisper PROD`	`prod-{uuid}`
Preview/PR	`Swisper PR-{number}`	`pr-{number}-{uuid}`

Additional Metadata¶

Traces can include additional environment metadata via tags:

# In Swisper, you can add environment tags to traces
# (Future SDK enhancement)
trace.tags = ["environment:production", "region:eu-west-1"]

Troubleshooting¶

Traces Not Appearing¶

Check SWISPER_STUDIO_ENABLED=true in Swisper
Verify SWISPER_STUDIO_PROJECT_ID matches a project in SwisperStudio
Check Redis connectivity: redis-cli ping
Check consumer logs: docker logs swisper_studio_consumer

Traces Appearing in Wrong Project¶

Verify each environment has a unique SWISPER_STUDIO_PROJECT_ID
Check if DEFAULT_PROJECT_ID is being used (project_id not set)

Consumer Not Processing¶

Check consumer is running: docker ps | grep consumer
Check Redis stream has events: redis-cli XLEN observability:events
Check consumer group exists: redis-cli XINFO GROUPS observability:events

Summary¶

To connect multiple Swisper environments to one SwisperStudio instance:

Create separate projects in SwisperStudio UI for each environment
Configure unique SWISPER_STUDIO_PROJECT_ID in each Swisper environment
Point all environments to the same Redis (or use separate with multiple consumers)
Filter by project in SwisperStudio UI to view traces from specific environments

This approach provides complete trace isolation while maintaining a unified observability platform.