sentry-protos

sentry-protos is the schema registry and generated-client-bindings repo behind Sentry’s internal service-to-service communication. Protobuf message and gRPC service definitions live under proto/, organized by product domain (Snuba, Seer, taskbroker, billing, conduit, and more) and version, and the repo’s build tooling compiles them into published Python and Rust client packages.

The Python package published to PyPI as sentry-protos is the generated output of that pipeline — a set of _pb2.py/gRPC stub modules an application imports to talk to Sentry’s backend services over gRPC without hand-writing serialization code. buf lint enforces backward compatibility on schema changes, and packages ship extremely frequently as new proto changes land on main.

What You Get

• Generated Python _pb2.py/gRPC stub modules for Sentry’s internal service schemas (Snuba, Seer, taskbroker, billing, conduit, and more)
• Versioned proto packages organized by product domain, each ending in an explicit version specifier
• Automatic backward-compatibility enforcement on schema changes via buf lint
• An alpha/beta/dev unstable-version convention that excludes in-development schemas from released client packages
• Very frequent automated releases (100+ tagged versions, multiple releases per week) driven by CI on every proto change merged to main

Common Use Cases

• Calling Sentry’s internal gRPC services (Snuba query layer, Seer AI service, taskbroker, billing) from Python code with generated, typed stubs
• Keeping client and server schema definitions in lockstep across Sentry’s polyglot (Python/Rust) service fleet
• Building internal tooling or integrations against Sentry’s service contracts without manually maintaining .proto files
• Tracking schema evolution safely via buf’s breaking-change detection before a new proto version ships

Under The Hood

Architecture — .proto files under proto/sentry_protos/<domain>/<version>/ are the single source of truth; make build-py and make build-rust invoke buf/protoc-based codegen (see py/generate.py) to emit language-specific client bindings into py/ and rust/, which are then packaged and published independently per language on every merge to main that touches proto/.

Tech Stack — the repo itself is majority Rust (code generation tooling and the Rust client crate) with a Python codegen/packaging layer (py/); buf.yaml configures schema linting and breaking-change checks, and GitHub Actions drives the automated version=auto release workflow.

Code Quality — the Python package includes a tests/ directory validating generated bindings import and function correctly; the real correctness guarantee, though, comes from buf lint’s breaking-change validation on the source .proto files rather than conventional unit tests of generated code, which is a reasonable tradeoff for a codegen-heavy repo.

API Design — because the Python package is entirely generated from .proto definitions, its API surface directly mirrors the protobuf message/service definitions (nested enums hoisted per language convention, one module per proto package); this keeps the Python API perfectly synchronized with the schema at the cost of the API being unreadable without cross-referencing the source .proto files.