Admin Interface

Overview

The admin command starts Snuba’s administrative web interface, providing a web-based UI for managing and monitoring the Snuba system. The admin interface offers tools for query debugging, system status monitoring, and configuration management.

snuba admin [OPTIONS]

Options

--debug

flag

Enable debug mode with auto-reload and detailed error pages.When enabled:

Automatic code reloading on file changes
Interactive debugger on errors
Detailed stack traces in browser
HTTP/1.1 protocol support

Important: In debug mode, --processes and --threads must be 1.

--log-level

string

Logging level to use for the admin interface.Available levels:

critical - Only critical errors
error - Error messages
warning - Warnings and errors
info - Informational messages
debug - Detailed debugging information

--processes

integer

default:"1"

Number of worker processes to spawn (minimum: 1).

Single process: Good for development or low-traffic deployments
Multiple processes: Better for production with concurrent requests

Must be 1 when --debug is enabled.

--threads

integer

Number of threads per worker process (minimum: 1).Threads within each process handle concurrent requests:

Single thread: Serialized request handling
Multiple threads: Concurrent request processing within the process

Must be 1 when --debug is enabled.

--backlog

integer

default:"128"

TCP socket connection backlog size (minimum: 128).Defines how many connections can queue waiting for acceptance:

Lower values: Clients may see connection refused during load spikes
Higher values: More connections can queue (more memory usage)

Default of 128 is suitable for most deployments.

Configuration

The admin interface uses settings from snuba/settings.py:

# Default admin interface settings
ADMIN_HOST = "127.0.0.1"
ADMIN_PORT = 1219

These can be overridden via environment variables:

export ADMIN_HOST=0.0.0.0
export ADMIN_PORT=8080
snuba admin

Examples

# Start in debug mode with auto-reload
snuba admin --debug --log-level debug

Accessing the Admin Interface

Once started, the admin interface is available at:

http://<ADMIN_HOST>:<ADMIN_PORT>/

Default: http://127.0.0.1:1219/

Available Features

The admin interface typically provides:

Query Tool

Test and debug SnQL queries interactively with formatted results

System Status

Monitor system health, cluster status, and resource usage

Config Viewer

View current configuration and storage definitions

Tracing Tools

Debug query execution and performance issues

Deployment Modes

Development Mode

For local development with hot-reloading:

snuba admin --debug

In debug mode, the admin interface runs using Werkzeug’s development server with:

Single-threaded operation
Auto-reload on code changes
Interactive debugger
HTTP/1.1 support

Access: http://127.0.0.1:1219/

Production Mode

For production deployments:

snuba admin --processes 4 --threads 8 --backlog 256

This configuration:

Runs using uWSGI for better performance
Handles concurrent requests efficiently
Suitable for production traffic
No auto-reload (restart required for code changes)

Never use --debug mode in production. It exposes sensitive debugging information and has poor performance characteristics.

Process Configuration

Choosing Process Count

Single Process
Multiple Processes

snuba admin --processes 1

Use when:

Development environment
Low traffic (< 10 requests/minute)
Running on limited resources
Debugging issues

Advantages:

Simple debugging
Lower memory usage
Easier to reason about

Disadvantages:

Limited concurrency
Single point of failure

snuba admin --processes 4 --threads 8

Use when:

Production environment
Multiple concurrent users
Need for high availability
Multi-core system

Advantages:

Better concurrency
Fault isolation
Utilizes multiple cores

Disadvantages:

Higher memory usage
More complex debugging

Calculating Workers

A common formula:

Processes = (2 × CPU_cores) + 1
Threads = 2 to 4

Example for 4-core system:

snuba admin --processes 9 --threads 4

Performance Tuning

Low-Traffic Deployment

# Minimal resource usage
snuba admin --processes 1 --threads 4 --backlog 128

Medium-Traffic Deployment

# Balanced configuration
snuba admin --processes 4 --threads 8 --backlog 256

High-Traffic Deployment

# Maximum throughput
snuba admin --processes 8 --threads 8 --backlog 512

Monitoring

Health Check

While the admin interface doesn’t expose a dedicated health endpoint, you can check if it’s running:

curl http://127.0.0.1:1219/

A successful response indicates the service is healthy.

Logs

Use appropriate log levels for monitoring:

# Minimal logging for production
snuba admin --log-level warning

Process Monitoring

In production, monitor the admin interface processes:

# Check running processes
ps aux | grep "snuba-admin"

# Monitor resource usage
top -p $(pgrep -f "snuba-admin")

Integration with Snuba

The admin interface runs as a separate service from the main Snuba API:

Separate Services
Development Server

# Terminal 1: Start API
snuba api --processes 4

# Terminal 2: Start Admin
snuba admin --processes 2

Best for production where admin traffic is separate from query traffic.

# Starts both API and Admin
snuba devserver

Both services start automatically:

API: http://127.0.0.1:1218/
Admin: http://127.0.0.1:1219/

Security Considerations

The admin interface provides powerful system access. In production:

Restrict Network Access
```
# Bind to localhost only
export ADMIN_HOST=127.0.0.1
snuba admin
```
Use a reverse proxy (nginx, Apache) with authentication.
Use Authentication Configure authentication in your reverse proxy.
Enable TLS Always use HTTPS in production via reverse proxy.
Firewall Rules Restrict admin port access to authorized IPs only.
Never Use Debug Mode Debug mode exposes code execution capabilities.

Troubleshooting

Port Already in Use

If the admin port is already bound:

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

# Change the port
export ADMIN_PORT=8080
snuba admin

Can't Start Multiple Processes in Debug

Error: “processes/threads can only be 1 in debug”

# Solution: Remove --debug or use single process
snuba admin --processes 1 --threads 1

# Or disable debug mode
snuba admin --processes 4 --threads 8

Connection Refused

If you can’t connect to the admin interface:

Verify it’s running:
```
ps aux | grep snuba-admin
```

Check the binding address:

# May need to bind to 0.0.0.0
export ADMIN_HOST=0.0.0.0
snuba admin

Check firewall rules:
```
# Allow admin port
sudo ufw allow 1219
```

High Memory Usage

If consuming too much memory:

Reduce process count:
```
snuba admin --processes 2 --threads 4
```
Monitor memory per process:
```
ps aux --sort=-rss | grep snuba-admin
```
Consider setting worker limits in uWSGI configuration

Slow Response Times

If the admin interface is slow:

Increase workers:
```
snuba admin --processes 4 --threads 8
```

Check ClickHouse connectivity:

# Admin queries ClickHouse for status
clickhouse-client --query "SELECT 1"

Enable connection pooling in settings.py
Monitor query performance in logs:
```
snuba admin --log-level debug
```

Common Workflows

Local Development

# Quick start with auto-reload
snuba admin --debug

# Access at http://127.0.0.1:1219/
# Make code changes and refresh browser

Testing Admin Changes

# Start with debug logging
snuba admin --debug --log-level debug

# Check logs for errors
# Test features in browser
# Iterate on changes

Production Deployment

Configure Environment

export ADMIN_HOST=127.0.0.1
export ADMIN_PORT=1219

Start Admin Service

snuba admin \
  --processes 4 \
  --threads 8 \
  --backlog 256 \
  --log-level warning

Configure Reverse Proxy

Setup nginx/Apache with:

TLS termination
Authentication
Rate limiting

Monitor

Check process health
Monitor memory usage
Review error logs

Environment Variables

The admin command respects:

# Service binding
ADMIN_HOST=0.0.0.0
ADMIN_PORT=1219

# Logging (when not specified via --log-level)
LOG_LEVEL=info

# General Snuba settings
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=9000

Next Steps

API Server

Learn about the main query API

Development Server

Start all services for development

Configuration

Configure Snuba settings

Monitoring

Monitor Snuba in production

Commands

Admin Interface

Overview

Options

Configuration

Examples

Accessing the Admin Interface

Available Features

Query Tool

System Status

Config Viewer

Tracing Tools

Deployment Modes

Development Mode

Production Mode

Process Configuration

Choosing Process Count

Calculating Workers

Performance Tuning

Low-Traffic Deployment

Medium-Traffic Deployment

High-Traffic Deployment

Monitoring

Health Check

Logs

Process Monitoring

Integration with Snuba

Security Considerations

Troubleshooting

Common Workflows

Local Development

Testing Admin Changes

Production Deployment

Environment Variables

Next Steps

API Server

Development Server

Configuration

Monitoring

Build docs developers (and LLMs) love

Commands

​Overview

​Options

​Configuration

​Examples

​Accessing the Admin Interface

​Available Features

Query Tool

System Status

Config Viewer

Tracing Tools

​Deployment Modes

​Development Mode

​Production Mode

​Process Configuration

​Choosing Process Count

​Calculating Workers

​Performance Tuning

​Low-Traffic Deployment

​Medium-Traffic Deployment

​High-Traffic Deployment

​Monitoring

​Health Check

​Logs

​Process Monitoring

​Integration with Snuba

​Security Considerations

​Troubleshooting

​Common Workflows

​Local Development

​Testing Admin Changes

​Production Deployment

​Environment Variables

​Next Steps

API Server

Development Server

Configuration

Monitoring

Build docs developers (and LLMs) love

Overview

Options

Configuration

Examples

Accessing the Admin Interface

Available Features

Deployment Modes

Development Mode

Production Mode

Process Configuration

Choosing Process Count

Calculating Workers

Performance Tuning

Low-Traffic Deployment

Medium-Traffic Deployment

High-Traffic Deployment

Monitoring

Health Check

Logs

Process Monitoring

Integration with Snuba

Security Considerations

Troubleshooting

Common Workflows

Local Development

Testing Admin Changes

Production Deployment

Environment Variables

Next Steps