Swisper Studio - Quick Start Configuration Guide¶

This guide walks you through setting up a new project in Swisper Studio and connecting Swisper to send traces.

Step 1: Create a Project in Swisper Studio¶

1. Open Swisper Studio: http://localhost:3000
2. Log in with your credentials
3. Click "New Project" or navigate to Projects
4. Fill in the project details:
5. Name: Your project name (e.g., "Swisper Production")
6. Description: Optional description
7. GitHub Repo URL: (Optional) Link to your repository
8. GitHub Token: (Optional) For GitHub integration
9. Click "Create"
10. Copy the Project ID from the project details page (you'll need this!)

Step 2: Configure Swisper to Send Traces¶

Add these environment variables to your Swisper .env file:

# Enable Swisper Studio integration
SWISPER_STUDIO_ENABLED=true

# Redis URL - points to Swisper Studio's Redis instance
# For local Docker setup (both running on same machine):
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380

# Your Project ID from Step 1 (copy from Swisper Studio UI)
SWISPER_STUDIO_PROJECT_ID=<paste-your-project-id-here>

# Stream name (must match Swisper Studio's consumer)
SWISPER_STUDIO_STREAM_NAME=observability:events

# Optional: Enable reasoning capture
SWISPER_STUDIO_CAPTURE_REASONING=true
SWISPER_STUDIO_REASONING_MAX_LENGTH=50000

Step 3: Restart Swisper¶

Important: You must recreate the container (not just restart) for .env changes to take effect:

cd /path/to/swisper
docker compose up -d backend --force-recreate

Step 4: Verify the Connection¶

1. Check Swisper logs for successful initialization:

   docker logs helvetiq-backend-1 2>&1 | grep SwisperStudio
   

You should see:

✅ SwisperStudio SDK initialized successfully
✅ SwisperStudio observability initialized (Redis Streams)
   Project ID: <your-project-id>

1. Send a test message in Swisper

2. Check Swisper Studio UI - traces should appear within seconds!

Redis URL Reference¶

Note: 172.17.0.1 is the Docker bridge gateway IP, allowing containers in different Docker networks to communicate via the host.

Troubleshooting¶

No traces appearing?¶

1. Check Project ID matches: The SWISPER_STUDIO_PROJECT_ID in Swisper must match the project you're viewing in the UI.

2. Verify Redis connectivity:

   docker exec helvetiq-backend-1 python -c "import redis; r = redis.from_url('redis://172.17.0.1:6380'); print('PING:', r.ping())"
   

3. Check container has correct env vars:

   docker exec helvetiq-backend-1 printenv | grep SWISPER_STUDIO
   

4. Ensure you recreated (not just restarted) the container after changing .env.

"Unknown event type: heartbeat" in logs?¶

This is normal - heartbeat events are used for health monitoring.

Environment-Specific Configuration¶

For multiple environments (dev, staging, production), create separate projects in Swisper Studio and configure each environment with its own SWISPER_STUDIO_PROJECT_ID:

This allows you to view traces from each environment separately in Swisper Studio.

Quick Reference¶

# Minimum required configuration
SWISPER_STUDIO_ENABLED=true
SWISPER_STUDIO_REDIS_URL=redis://172.17.0.1:6380
SWISPER_STUDIO_PROJECT_ID=<your-project-id>
SWISPER_STUDIO_STREAM_NAME=observability:events