Skip to content

Swisper Backend Configuration for SwisperStudio Integration

Version: 1.0
Date: 2025-11-20
Audience: Swisper Backend Team

Overview

For Swisper to send observability events to SwisperStudio, it needs to be configured with: 1. SwisperStudio Redis URL (where to publish events) 2. SwisperStudio Project ID (which project in Studio) 3. SDK settings (optional tuning)

Required Configuration

1. Environment Variables

Add these to Swisper's backend configuration:

# SwisperStudio Redis Connection
SWISPER_STUDIO_REDIS_URL=redis://swisper_studio_redis:6379

# SwisperStudio Project ID (get from Studio UI)
SWISPER_STUDIO_PROJECT_ID=0d7aa606-cb29-4a31-8a59-50fa61151a32

# Enable/disable observability (optional, defaults to true)
SWISPER_STUDIO_ENABLED=true

# Stream name (optional, defaults to observability:events)
SWISPER_STUDIO_STREAM_NAME=observability:events

Environment-Specific URLs

Development (Local Docker)

If both Swisper and SwisperStudio run via Docker Compose:

# Option 1: Using container name (requires shared network)
SWISPER_STUDIO_REDIS_URL=redis://swisper_studio_redis:6379

# Option 2: Using Docker host IP (easier, no network setup)
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380

How to find Docker host IP: 

docker inspect swisper_studio_redis | grep IPAddress
# Use the IP shown

Staging Environment

# Internal hostname (if co-located)
SWISPER_STUDIO_REDIS_URL=redis://swisper-studio-redis.internal:6379

# Or external hostname with port
SWISPER_STUDIO_REDIS_URL=redis://staging-studio-redis.fintama.com:6380

Production Environment

# Internal hostname (recommended if co-located)
SWISPER_STUDIO_REDIS_URL=redis://swisper-studio-redis.prod.internal:6379

# Or external hostname
SWISPER_STUDIO_REDIS_URL=redis://prod-studio-redis.fintama.com:6380

Docker Compose Configuration

Option 1: Using Docker Host IP (Easiest) ✅

No network changes needed!

# swisper/docker-compose.yml
version: '3.8'

services:
  backend:
    image: swisper-backend:latest
    environment:
      # Swisper's own Redis (operational)
      REDIS_URL: redis://redis:6379

      # SwisperStudio's Redis (observability)
      SWISPER_STUDIO_REDIS_URL: redis://172.17.0.1:6380  # Docker host IP
      SWISPER_STUDIO_PROJECT_ID: 0d7aa606-cb29-4a31-8a59-50fa61151a32
      SWISPER_STUDIO_ENABLED: "true"

    depends_on:
      - redis

How it works: - 172.17.0.1 is the default Docker bridge gateway - SwisperStudio Redis is exposed on host port 6380 - Swisper containers can reach it via 172.17.0.1:6380

Verify host IP: 

# From inside Swisper container
docker exec swisper-backend ping -c 1 172.17.0.1

# Test Redis connection
docker exec swisper-backend redis-cli -h 172.17.0.1 -p 6380 ping
# Should return: PONG

Option 2: Using Shared Docker Network 🔗

If you prefer container names:

# swisper/docker-compose.yml
version: '3.8'

services:
  backend:
    image: swisper-backend:latest
    environment:
      REDIS_URL: redis://redis:6379
      SWISPER_STUDIO_REDIS_URL: redis://swisper_studio_redis:6379
      SWISPER_STUDIO_PROJECT_ID: 0d7aa606-cb29-4a31-8a59-50fa61151a32

    networks:
      - helvetiq_default
      - swisper_studio_network  # Add Studio's network

    depends_on:
      - redis

networks:
  helvetiq_default:
    driver: bridge
  swisper_studio_network:
    external: true  # Reference Studio's network

Setup: 

# 1. Create Studio network (if not exists)
docker network create swisper_studio_network

# 2. Connect Studio Redis to this network
docker network connect swisper_studio_network swisper_studio_redis

# 3. Restart Swisper
cd /path/to/swisper
docker compose restart backend

Verify connection: 

docker exec swisper-backend ping -c 1 swisper_studio_redis

docker exec swisper-backend redis-cli -h swisper_studio_redis ping
# Should return: PONG

Configuration Files

Create/update: swisper/backend/.env

# Swisper Backend Environment Variables

# Swisper's own Redis
REDIS_URL=redis://redis:6379

# SwisperStudio Integration
SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380
SWISPER_STUDIO_PROJECT_ID=0d7aa606-cb29-4a31-8a59-50fa61151a32
SWISPER_STUDIO_STREAM_NAME=observability:events

# Optional: Capture LLM reasoning (<think> tags)
SWISPER_STUDIO_CAPTURE_REASONING=true
SWISPER_STUDIO_REASONING_MAX_LENGTH=50000

Then reference in docker-compose.yml:

services:
  backend:
    env_file:
      - ./backend/.env

Using config.py (Python Config)

File: apps/backend/swisper/core/config.py

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # ... existing settings ...

    # SwisperStudio Integration (Observability)
    SWISPER_STUDIO_ENABLED: bool = True
    SWISPER_STUDIO_REDIS_URL: str = "redis://172.17.0.1:6380"
    SWISPER_STUDIO_STREAM_NAME: str = "observability:events"
    SWISPER_STUDIO_PROJECT_ID: str = ""  # Required: Get from Studio UI
    SWISPER_STUDIO_CAPTURE_REASONING: bool = True
    SWISPER_STUDIO_REASONING_MAX_LENGTH: int = 50000

    class Config:
        env_file = ".env"
        case_sensitive = True

settings = Settings()

How to Get Project ID

Step 1: Access SwisperStudio UI

Development: 

http://localhost:3000

Staging: 

https://swisper-studio-staging.fintama.com

Production: 

https://swisper-studio.fintama.com

Step 2: Create/Select Project

  1. Navigate to "Projects" page
  2. Click "Create Project" (or select existing)
  3. Fill in:
  4. Name: Swisper Production (or Swisper Development)
  5. Description: Main Swisper application
  6. Click "Save"

Step 3: Copy Project ID

  1. Click on the project
  2. Look at the URL: /projects/{PROJECT_ID}/traces
  3. Copy the UUID (e.g., 0d7aa606-cb29-4a31-8a59-50fa61151a32)
  4. Paste into SWISPER_STUDIO_PROJECT_ID

Example: 

URL: http://localhost:3000/projects/0d7aa606-cb29-4a31-8a59-50fa61151a32/traces
                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                     This is your PROJECT_ID

Verification Steps

1. Check Configuration Loaded

# From Swisper backend container
docker exec swisper-backend python -c "
from app.core.config import settings
print(f'SwisperStudio enabled: {settings.SWISPER_STUDIO_ENABLED}')
print(f'Redis URL: {settings.SWISPER_STUDIO_REDIS_URL}')
print(f'Project ID: {settings.SWISPER_STUDIO_PROJECT_ID}')
"

Expected output: 

SwisperStudio enabled: True
Redis URL: redis://172.17.0.1:6380
Project ID: 0d7aa606-cb29-4a31-8a59-50fa61151a32

2. Check Redis Connection

# Test connection from Swisper backend
docker exec swisper-backend redis-cli -h 172.17.0.1 -p 6380 ping
# Should return: PONG

# Check if stream exists
docker exec swisper-backend redis-cli -h 172.17.0.1 -p 6380 XLEN observability:events
# Should return: 0 (or number of events)

3. Trigger Test Event

# Send a test message through Swisper
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, testing observability"}'

# Check events in Studio Redis
docker exec swisper_studio_redis redis-cli XLEN observability:events
# Should show > 0

# Check events in Studio UI
# Navigate to: http://localhost:3000/projects/{PROJECT_ID}/traces
# Should see your test trace

4. Check Logs

# Swisper backend logs
docker logs swisper-backend | grep -i "swisperstudio"

# Should see:
# ✅ SwisperStudio observability initialized (Redis Streams)
# ✅ LLM prompt capture enabled
# ✅ GlobalSupervisor graph wrapped with SwisperStudio tracing

Troubleshooting

Issue: "Cannot connect to Redis"

Symptom: 

⚠️ SwisperStudio observability initialization failed: Connection refused

Solutions:

1. Check SwisperStudio Redis is running: 

docker ps | grep swisper_studio_redis
# Should show running container

2. Check port is exposed: 

docker port swisper_studio_redis
# Should show: 6379/tcp -> 0.0.0.0:6380

3. Test connection from host: 

redis-cli -h 127.0.0.1 -p 6380 ping
# Should return: PONG

4. Check Docker host IP: 

# From Swisper container
docker exec swisper-backend ip route | grep default
# Should show: default via 172.17.0.1

5. Update SWISPER_STUDIO_REDIS_URL: 

# Use the IP from step 4
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380

Issue: "Project ID not found"

Symptom: 

Events published but not visible in Studio UI

Solutions:

1. Verify Project ID is correct: 

# Check config
docker exec swisper-backend python -c "
from app.core.config import settings
print(settings.SWISPER_STUDIO_PROJECT_ID)
"

2. Check project exists in Studio: 

# Query Studio DB
docker exec swisper_studio_postgres psql -U studio_user -d swisper_studio -c \
  "SELECT id, name FROM projects;"

3. Create project if missing: - Open Studio UI: http://localhost:3000 - Go to Projects → Create New - Copy the new Project ID - Update Swisper config

Issue: "Events not appearing in Studio"

Symptom: - Events published to Redis - But not visible in Studio UI

Solutions:

1. Check Studio consumer is running: 

docker logs swisper_studio_backend | grep consumer

# Should see:
# ✅ Observability consumer started

2. Check stream has events: 

docker exec swisper_studio_redis redis-cli XLEN observability:events
# Should show > 0

3. Check consumer is processing: 

docker logs swisper_studio_backend | grep "Processing batch"

# Should see:
# Processing batch of 10 events

4. Check for errors: 

docker logs swisper_studio_backend | grep -i error

5. Restart Studio backend: 

cd /root/projects/swisper_studio
docker compose restart backend

Configuration Summary

Quick Setup Checklist

  • [ ] SwisperStudio Redis is running (docker ps | grep swisper_studio_redis)
  • [ ] Redis port exposed (6380 on host)
  • [ ] Swisper config has SWISPER_STUDIO_REDIS_URL set
  • [ ] Project created in Studio UI
  • [ ] SWISPER_STUDIO_PROJECT_ID set in Swisper config
  • [ ] Swisper backend restarted
  • [ ] Test event sent successfully
  • [ ] Events visible in Studio UI

Environment Examples

Development (localhost)

SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380
SWISPER_STUDIO_PROJECT_ID=0d7aa606-cb29-4a31-8a59-50fa61151a32

Staging

SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://swisper-studio-redis.staging.internal:6379
SWISPER_STUDIO_PROJECT_ID=abc12345-6789-1234-5678-901234567890

Production

SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://swisper-studio-redis.prod.internal:6379
SWISPER_STUDIO_PROJECT_ID=def12345-6789-1234-5678-901234567890
  • docs/architecture/redis_separation_architecture.md - Architecture overview
  • docs/guides/swisper_studio_sdk_integration_guide.md - SDK integration
  • docs/deployment/swisper_studio_deployment.md - Studio deployment

Contact: SwisperStudio Team
Support: swisper-studio-support@fintama.com (update with actual contact)
Last Updated: 2025-11-20