Sentry Protobuf Definitions (Generated Python Code)

Common errors

• ModuleNotFoundError: No module named 'sentry_protos.some_service.v1.some_service_pb2'

  cause The `sentry-protos` package is either not installed, or the specific protobuf definition you are trying to import does not exist in your installed version (e.g., it's a new service/version or has been renamed).
  fix Ensure `sentry-protos` is installed (`pip install sentry-protos`). Verify the exact module path by checking the `sentry_protos` directory in your `site-packages` or by looking at the Sentry GitHub repository. If it's a new service, upgrade `sentry-protos` to the latest version.

• TypeError: Parameter to MergeFrom() must be instance of same class: expected sentry_protos.snuba.v1.snuba_pb2.QueryRequest got sentry_protos.snuba.v1.snuba_pb2.QueryRequest

  cause This cryptic error usually indicates a protobuf version mismatch between different parts of your application or dependencies, or an incompatibility when trying to merge/assign messages that, despite having the same class name, were generated from slightly different `.proto` definitions or by different `protobuf` runtime versions.
  fix Ensure all parts of your application are using the same installed version of `sentry-protos` and `protobuf`. Try updating both `pip install --upgrade sentry-protos protobuf` and rebuilding any environments to ensure consistent versions. Avoid mixing message objects created from different `sentry-protos` installations or different `protobuf` runtime versions.

Warnings

• breaking As `sentry-protos` is a pre-1.0 library (version 0.x.y), minor version bumps (e.g., 0.8.x to 0.9.x) can introduce breaking changes to message definitions or removal of fields/services. Always review the changelog when upgrading.
  Fix: Pin your `sentry-protos` dependency to a specific minor version (e.g., `sentry-protos~=0.8.0`) and carefully test upgrades.
• gotcha This package contains only the generated Python message definitions (`_pb2.py` files). It does not include gRPC service stubs or client/server code (`_pb2_grpc.py` files). If you need to implement gRPC services or clients based on these protos, you will need `grpcio` and `grpcio-tools` and will have to generate those stubs yourself.
  Fix: For gRPC client/server code, use `grpcio` and `grpcio-tools` with the original `.proto` files to generate service stubs. `sentry-protos` is strictly for data serialization/deserialization.
• gotcha Due to Sentry's continuous development, upstream `.proto` definitions are frequently updated. This means `sentry-protos` receives regular updates to reflect new fields, messages, or services. Older versions of `sentry-protos` may lack definitions for newer features or services, leading to `AttributeError` or unexpected behavior.
  Fix: Ensure your `sentry-protos` package is kept up-to-date (`pip install --upgrade sentry-protos`) to access the latest protobuf definitions. If you encounter missing fields or messages, an upgrade is often the first step.

Install

• pip install sentry-protos Install latest version

Imports

• snuba_pb2
  wrong:

  import snuba_pb2

  correct:

  from sentry_protos.snuba.v1 import snuba_pb2

  Generated protobuf modules are nested within `sentry_protos` by service and version.
• MyMessage

  from sentry_protos.some_service.vX import some_service_pb2

  The exact import path depends on the specific Sentry service and protobuf version you need.

Quickstart

This quickstart demonstrates how to import a specific generated protobuf message (Snuba QueryRequest) and instantiate it, setting its fields. Remember to replace `snuba.v1` and `snuba_pb2` with the actual service and version you intend to use.

from sentry_protos.snuba.v1 import snuba_pb2

# Create a QueryRequest message
query_request = snuba_pb2.QueryRequest(
    dataset='events',
    query="MATCH (event) SELECT event.id"
)

print(f"Successfully created Snuba QueryRequest:")
print(f"  Dataset: {query_request.dataset}")
print(f"  Query: {query_request.query}")

# You can also set fields dynamically
another_query = snuba_pb2.QueryRequest()
another_query.dataset = 'transactions'
another_query.query = 'MATCH (transaction) SELECT transaction.duration'

print(f"\nAnother QueryRequest: {another_query.query}")