Development Server

Overview

The devserver command provides a convenient way to start all necessary Snuba services for local development. It handles bootstrapping, migrations, and orchestrates multiple processes including the API server, consumers, and background workers.

snuba devserver [OPTIONS]

This command uses Honcho to manage multiple processes and provides a unified console output showing logs from all services.

Options

--bootstrap/--no-bootstrap

boolean

default:"true"

Whether to run bootstrap operations before starting services.Bootstrap includes:

Creating Kafka topics (unless --no-migrate is used with bootstrap)
Running database migrations

Use --no-bootstrap to skip initialization if your environment is already set up.

--workers/--no-workers

boolean

default:"true"

Whether to start background workers (consumers, subscriptions, etc.).With --workers: Starts all services including consumers and processors With --no-workers: Starts only the API server

--log-level

string

default:"info"

Logging level for all processes.Available levels:

critical - Only critical errors
error - Error messages
warning - Warnings and errors
info - Informational messages (default)
debug - Detailed debugging output
trace - Verbose trace-level logging (for Rust consumers)

What Gets Started

The devserver starts different services based on configuration and feature flags:

Core Services (Always)

API Server

Main HTTP API for query processingEndpoint: Default http://localhost:1218

Admin Interface

Administrative web UIEndpoint: Default http://localhost:1219

Data Processing (When —workers enabled)

Transaction Processing

transaction-consumer - Processes transaction/span events
Command: snuba rust-consumer --storage=transactions
Consumer group: transactions_group

Error Processing

errors-consumer - Processes error events
replacer - Handles data replacements and updates
Consumer group: errors_group

Outcomes Processing

outcomes-consumer - Standard outcomes
outcomes-billing-consumer - Billing outcomes from separate topic
Consumer group: outcomes_group / outcomes_billing_group

Subscriptions

Subscription services for events and transactions:Combined Mode (default):

subscriptions-scheduler-executor-events
subscriptions-scheduler-executor-transactions
subscriptions-scheduler-executor-eap-items

Separate Mode (if configured):

subscriptions-scheduler-events + subscriptions-executor-events
subscriptions-scheduler-transactions + subscriptions-executor-transactions
subscriptions-scheduler-eap-items + subscriptions-executor-eap-items

Optional Services (Feature Flags)

Metrics (ENABLE_SENTRY_METRICS_DEV)

When enabled, starts consumers for:

metrics-consumer - Legacy metrics
generic-metrics-distributions-consumer
generic-metrics-sets-consumer
generic-metrics-counters-consumer
generic-metrics-gauges-consumer

If ENABLE_METRICS_SUBSCRIPTIONS is also enabled:

Subscription schedulers and executors for each metric type

Profiles (ENABLE_PROFILES_CONSUMER)

When enabled, starts:

profiles - Profile data consumer
profile_chunks - Profile chunks consumer
functions - Functions data consumer

Replays (ENABLE_REPLAYS_CONSUMER)

When enabled, starts:

replays-consumer - Session replay events

Issues (ENABLE_ISSUE_OCCURRENCE_CONSUMER)

When enabled, starts:

issue-occurrence-consumer - Generic issue events

Group Attributes (ENABLE_GROUP_ATTRIBUTES_CONSUMER)

When enabled, starts:

group-attributes-consumer - Group attribute updates

Lightweight Deletions (ENABLE_LW_DELETIONS_CONSUMER)

When enabled, starts:

lw-deletions-consumer - Processes deletion requests

EAP Items (Always enabled in dev)

eap-items-consumer - Events Analytics Platform items
Uses RowBinary format

Examples

# Start everything with default settings
snuba devserver

Startup Sequence

When you run snuba devserver, the following happens:

Bootstrap (if enabled)

Runs snuba bootstrap --force --no-migrate to create Kafka topics.If this fails and --workers is enabled, the command exits immediately.

Migrations

Runs snuba migrations migrate --force to apply all pending database migrations.If this fails, the command exits immediately.

Process Manager Initialization

Honcho manager is initialized with all configured daemons.

Service Startup

All services start in parallel with unified logging output.

If --no-workers is specified, the bootstrap phase still runs (unless --no-bootstrap is also used), but only the API server process is started.

Default Consumer Configuration

All Rust consumers started by devserver use these common options:

--use-rust-processor
--auto-offset-reset=latest
--no-strict-offset-reset
--enforce-schema
--log-level={specified_level}

This configuration:

Uses Rust-based message processing for performance
Starts consuming from the latest messages (doesn’t replay old data)
Allows offset reset even when offsets exist
Enforces schema validation on incoming messages
Uses the log level specified via --log-level option

Process Management

Viewing Logs

All process logs are multiplexed to stdout with the process name prefix:

api             | 2026-03-09 10:30:45 [INFO] Starting Snuba API server
transaction-co  | 2026-03-09 10:30:45 [INFO] Consumer Starting
errors-consume  | 2026-03-09 10:30:45 [INFO] Consumer Starting
admin           | 2026-03-09 10:30:45 [INFO] Starting admin interface

Stopping Services

Press Ctrl+C to gracefully stop all services. Honcho will:

Send SIGTERM to all processes
Wait for graceful shutdown
Report exit codes

Exit Codes

The devserver command exits with:

0 - All services shut down cleanly
>0 - Bootstrap or migration failure, or one or more services crashed

Configuration

The devserver respects various settings from snuba/settings.py:

Service Endpoints

HOST / PORT - API server binding (default: 127.0.0.1:1218)
ADMIN_HOST / ADMIN_PORT - Admin interface (default: 127.0.0.1:1219)

Feature Flags

ENABLE_SENTRY_METRICS_DEV - Enable metrics consumers
ENABLE_PROFILES_CONSUMER - Enable profiling consumers
ENABLE_REPLAYS_CONSUMER - Enable replay consumer
ENABLE_ISSUE_OCCURRENCE_CONSUMER - Enable issue consumer
ENABLE_GROUP_ATTRIBUTES_CONSUMER - Enable group attributes
ENABLE_LW_DELETIONS_CONSUMER - Enable lightweight deletions
ENABLE_METRICS_SUBSCRIPTIONS - Enable metrics subscriptions

Subscription Mode

SEPARATE_SCHEDULER_EXECUTOR_SUBSCRIPTIONS_DEV - Run scheduler/executor separately
Default: false (combined scheduler-executor)

Common Workflows

First Time Setup

Initial Bootstrap

Start with full bootstrap:

snuba devserver

This creates all Kafka topics and runs migrations.

Verify Services

Check that services are running:

# Test API
curl http://localhost:1218/health

# Access Admin UI
open http://localhost:1219

Generate Test Data

Use Sentry’s development server or scripts to generate test events.

Daily Development

# Quick restart without bootstrap
snuba devserver --no-bootstrap

# Or API only for testing queries
snuba devserver --no-workers --no-bootstrap

Debugging Issues

# Enable debug logging to see detailed consumer behavior
snuba devserver --log-level debug

Reset Environment

# Stop devserver
# Ctrl+C

# Clear data (if needed)
# - Delete ClickHouse tables
# - Reset Kafka topics

# Fresh bootstrap
snuba devserver

Troubleshooting

Bootstrap Fails

If bootstrap fails to connect to Kafka:

Check that Kafka is running
Verify Kafka configuration in settings

Try with longer timeout:

# Kafka has up to 60 seconds to become available
snuba devserver

Migration Errors

If migrations fail:

# Check ClickHouse is running
clickhouse-client --query "SELECT 1"

# View migration status
snuba migrations list

# Fix any in-progress migrations
snuba migrations reverse-in-progress

# Retry
snuba devserver

Consumer Won't Start

If a consumer fails to start:

Check the specific consumer logs in the output
Verify storage configuration
Ensure Kafka topics exist:
```
snuba bootstrap --force --no-migrate
```

Check ClickHouse connections:

snuba api --debug  # Will show connection errors

Port Already in Use

If ports are already bound:

# Check what's using the port
lsof -i :1218
lsof -i :1219

# Kill the process or change settings.py

Out of Memory

If running out of memory with all services:

Start with fewer services:
```
snuba devserver --no-workers
```
Disable optional consumers in settings.py
Reduce consumer batch sizes in source code

Environment Variables

The devserver sets:

PYTHONUNBUFFERED=1  # Ensures logs are immediately visible
RUST_LOG={log_level}  # Configures Rust consumer logging

You can also set:

# Override Kafka bootstrap servers
export KAFKA_BROKER=kafka:9092

# Configure ClickHouse
export CLICKHOUSE_HOST=localhost

# Enable specific features
export ENABLE_SENTRY_METRICS_DEV=1

snuba devserver

Performance Tips

Faster Restarts

# Skip bootstrap for faster startup
snuba devserver --no-bootstrap

# Or even faster - API only
snuba devserver --no-workers --no-bootstrap

Resource Usage

To reduce resource usage during development:

Disable unnecessary features in settings.py:

ENABLE_SENTRY_METRICS_DEV = False
ENABLE_PROFILES_CONSUMER = False
ENABLE_REPLAYS_CONSUMER = False

Start API only when not testing consumers:
```
snuba devserver --no-workers
```
Use latest offset to avoid processing old data:
- Already configured in devserver default options

Integration with Sentry Development

When developing Sentry locally:

Start Sentry’s dependencies (including Kafka, ClickHouse)
Start Snuba devserver:
```
snuba devserver
```
Start Sentry development server
Generate events through Sentry UI or SDK
Query data through Snuba API or Sentry

Next Steps

Consumer Details

Learn about individual consumer options

Migrations

Understand migration management

Admin Interface

Explore administrative features

API Documentation

Query API reference

Commands

Development Server

Overview

Options

What Gets Started

Core Services (Always)

API Server

Admin Interface

Data Processing (When —workers enabled)

Optional Services (Feature Flags)

Examples

Startup Sequence

Default Consumer Configuration

Process Management

Viewing Logs

Stopping Services

Exit Codes

Configuration

Common Workflows

First Time Setup

Daily Development

Debugging Issues

Reset Environment

Troubleshooting

Environment Variables

Performance Tips

Faster Restarts

Resource Usage

Integration with Sentry Development

Next Steps

Consumer Details

Migrations

Admin Interface

API Documentation

Build docs developers (and LLMs) love

Commands

​Overview

​Options

​What Gets Started

​Core Services (Always)

API Server

Admin Interface

​Data Processing (When —workers enabled)

​Optional Services (Feature Flags)

​Examples

​Startup Sequence

​Default Consumer Configuration

​Process Management

​Viewing Logs

​Stopping Services

​Exit Codes

​Configuration

​Common Workflows

​First Time Setup

​Daily Development

​Debugging Issues

​Reset Environment

​Troubleshooting

​Environment Variables

​Performance Tips

​Faster Restarts

​Resource Usage

​Integration with Sentry Development

​Next Steps

Consumer Details

Migrations

Admin Interface

API Documentation

Build docs developers (and LLMs) love

Overview

Options

What Gets Started

Core Services (Always)

Data Processing (When —workers enabled)

Optional Services (Feature Flags)

Examples

Startup Sequence

Default Consumer Configuration

Process Management

Viewing Logs

Stopping Services

Exit Codes

Configuration

Common Workflows

First Time Setup

Daily Development

Debugging Issues

Reset Environment

Troubleshooting

Environment Variables

Performance Tips

Faster Restarts

Resource Usage

Integration with Sentry Development

Next Steps