sentry-protos

Protocol buffers and gRPC schema for cross-process communication. Contains tooling to generate python and rust client bindings.

📗 Notion documentation

Defining schemas

Message schemas are defined in the protos directory. Messages and services are organized by service or product domain and version.

All proto files are required to define a package that reflects the filesystem path to the proto file, and must end in a version specifier.

Backwards compatibility

We use buf lint to validate that changes to existing schemas are backwards compatible with previously published schemas. If breaking changes are required it is recommended to create a new version package instead of trying to ship a potentially breaking change.

Unstable versions

While features are in development, we occasionally need to break backwards compatibility. Proto packages whose version ends in alpha or beta are treated as unstable: they are exempt from buf breaking-change validation and are excluded from released client packages, which prevents in-development schemas from being used in production workloads.

For example: sentry_protos.sentry.confabulator.v1beta would not be subject to backwards compatibility.

Two separate mechanisms recognize slightly different suffixes, so stick to alpha/beta to stay covered by both:

• buf (breaking-change checks, via ignore_unstable_packages) also treats a test suffix (e.g. v1test) as unstable.
• The Python and Rust build scripts (release packaging) instead recognize a dev suffix (e.g. v1dev).

Local development workflow

sentry-protos makes it easy to develop and test protobuf/grpc changes locally before making pull requests.

You'll need a local clone of this repository to start.

Python

From the root of sentry-protos run:

make build-py

Then in your application install the python bindings with pip.

# CWD is in your python application
pip install -e ../sentry-protos/py --config-settings editable_mode=strict

As you make changes to proto files, you will need to regenerate bindings with make build-py.

Rust

From the root of sentry-protos run:

make build-rust

Your application's Cargo.toml will need the following:

[dependencies]
sentry_protos = "0.1.0"

[patch.crates-io]
sentry_protos = { path = "../sentry-protos/rust/" }

Rust conventions

Rust code generation applies some naming conventions that you need to keep in mind when consuming generated code.

Enums within Messages

Enums that are nested within messages will be hoisted into a namespace matching the snake_case name of the message. For example:

// Defined in sentry_protos/snuba/v1alpha/trace_item_attribute.proto
message AttributeKey {
  enum Type {
    TYPE_UNSPECIFIED = 0;
    TYPE_BOOLEAN = 1;
  }
}

The Type enum would be available as sentry_protos::snuba::v1alpha::attribute_key::Type. While AttributeKey can be imported from sentry_protos::snuba::v1alpha::AttributeKey.

Releasing

Releases are automated for merges to main that include changes under proto/. The release GitHub Actions workflow runs with version=auto, which creates the next version and publishes packages for each supported language.

Manual release workflow dispatch

If you need to manually run a release with explicit inputs (for example custom version or force), use the release workflow in GitHub Actions:

Select release

click Run Workflow to create a new release, update version according to semver guidelines