cell-architecture
Reference and active migration guide for Sentry's cell architecture. Explains what cells and localities are and why they're different, how requests reach cells via Synapse API routing, ingestion routing, and the control silo gateway, and how to safely query cross-cell data without silently missing results. The migration section covers how to do migration work: draining the URL_NAME_TO_ACTION registry in test_urls.py to zero (with a recipe for each action type), rolling deploy safety and the two-phase pattern required by independent sentry/getsentry deploys, and the region -> cell rename including what not to rename (DB columns, AWS refs, uptime regions, billing address). Also documents known issues with proposed fixes: integration TeamLinkageView routing, Jira cross-cell fan-out, and relocation endpoint routing.
Install
Install this Claude and Codex skill with the command below. The command stays visible even when copy support is unavailable.
git clone https://github.com/getsentry/sentry /tmp/sentry && ln -s /tmp/sentry/.agents/skills/cell-architecture ~/.claude/skills/cell-architectureFrom README
Cells Cell vs Locality These are two different layers of the architecture. Cell — a self-contained Sentry deployment that owns a subset of organizations. Each cell runs its own full stack — Getsentry, Snuba, Seer, Relay, Kafka, Symbolicator, and others — on an isolated network with no direct cell-to-cell communication. OrganizationMapping.cellname records which cell an org lives in. See Paths Into a Cell for how cells communicate with the outside world. Locality — a named collection of cells, representing either a data residency zone (for multi-tenant customers, e.g. "us", "de") or a dedicated deployment for a single customer (e.g. s4s2). Multi-tenant customers choose a locality when creating an organization; single-tenant localities are provisioned privately and not customer-selectable. Each locality maps to a subdomain (us.sentry.io, de.sentry.io or s4s2.sentry.io). Note: "region" is the old name for "cell". The codebase is actively being migrated. See Active Migration for details.