snuba

packaged by Chainguard

Chainguard Container for snuba

Snuba is the Sentry service that ingests events into ClickHouse and serves queries over them through the SnQL and MQL languages.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/snuba:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

Chainguard's Snuba image is comparable to the upstream getsentry/snuba and ghcr.io/getsentry/snuba images. It keeps the upstream entrypoint script, the default api command, the /usr/src/snuba working directory, and the unprivileged snuba user (UID 1000), so it works as a replacement in self-hosted Sentry and other deployments that pass Snuba subcommands as the container command. It differs from the upstream image in the following ways:

• The Python virtual environment is at /usr/src/snuba/.venv instead of /.venv, and its bin directory is first on PATH. The snuba CLI is also available at /usr/bin/snuba.
• The image is built from source on Chainguard OS and does not include a shell or package manager. Use the -dev variant if you need a shell for debugging.

Getting Started

Snuba stores data in ClickHouse and uses Redis for its query cache and runtime configuration. Create a network and start both dependencies:

docker network create snuba
docker run -d --name clickhouse --network snuba \
  cgr.dev/ORGANIZATION/clickhouse:latest server -- --listen_host 0.0.0.0
docker run -d --name redis --network snuba cgr.dev/ORGANIZATION/valkey:latest

The image entrypoint passes Snuba subcommands to the snuba CLI, as the upstream image does. Create the ClickHouse tables by running the same bootstrap step that self-hosted Sentry runs on install. The --no-kafka flag skips Kafka topic creation, which is useful when you only want to query data:

docker run --rm --network snuba \
  -e SNUBA_SETTINGS=self_hosted -e CLICKHOUSE_HOST=clickhouse -e REDIS_HOST=redis \
  cgr.dev/ORGANIZATION/snuba:latest bootstrap --no-kafka --force

Start the query API, which is the default command and listens on port 1218:

docker run -d --name snuba-api --network snuba -p 1218:1218 \
  -e SNUBA_SETTINGS=self_hosted -e CLICKHOUSE_HOST=clickhouse -e REDIS_HOST=redis \
  cgr.dev/ORGANIZATION/snuba:latest

Write a few outcomes rows directly to ClickHouse, then read them back through the SnQL API:

docker exec clickhouse clickhouse client -q "INSERT INTO outcomes_raw_local (org_id, project_id, key_id, timestamp, outcome, reason, event_id, quantity, quantity64, category) VALUES (42, 7, 1, now(), 0, NULL, generateUUIDv4(), 3, 3, 1), (42, 7, 1, now(), 0, NULL, generateUUIDv4(), 4, 4, 1)"

START=$(docker exec clickhouse clickhouse client -q "SELECT formatDateTime(now() - INTERVAL 1 HOUR, '%Y-%m-%dT%H:%i:%S')")
END=$(docker exec clickhouse clickhouse client -q "SELECT formatDateTime(now() + INTERVAL 1 HOUR, '%Y-%m-%dT%H:%i:%S')")
curl -s -X POST -H 'Content-Type: application/json' http://localhost:1218/outcomes/snql \
  -d "{\"query\": \"MATCH (outcomes) SELECT sum(quantity) AS total WHERE org_id = 42 AND timestamp >= toDateTime('$START') AND timestamp < toDateTime('$END')\", \"tenant_ids\": {\"organization_id\": 42, \"referrer\": \"readme\"}}"

The response contains the aggregated total among other query metadata:

{"data": [{"total": 7}], "meta": [{"name": "total", "type": "UInt64"}], ...}

Other subcommands, such as rust-consumer, subscriptions-scheduler-executor, and cleanup, run the same way by passing them as the container command.

Configuration

Snuba reads its settings from environment variables, selected by the SNUBA_SETTINGS module. For a deployment that mirrors self-hosted Sentry, set SNUBA_SETTINGS=self_hosted and point Snuba at your ClickHouse, Redis, and Kafka services:

docker run -d --name snuba-api -p 1218:1218 \
  -e SNUBA_SETTINGS=self_hosted \
  -e CLICKHOUSE_HOST=clickhouse.internal \
  -e CLICKHOUSE_HTTP_PORT=8123 \
  -e REDIS_HOST=redis.internal \
  -e DEFAULT_BROKERS=kafka.internal:9092 \
  cgr.dev/ORGANIZATION/snuba:latest

Use the same environment for the consumer and scheduler containers so that every Snuba process writes to and reads from the same storage.

On Kubernetes, set enableServiceLinks: false in the pod spec when your Redis Service is named redis. Otherwise Kubernetes injects REDIS_PORT=tcp://..., which overrides the Redis port Snuba reads.

Documentation and Resources

• Snuba project and documentation
• Self-hosted Sentry

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.