{"id":10222,"library":"sentry-protos","title":"Sentry Protobuf Definitions (Generated Python Code)","description":"sentry-protos provides the auto-generated Python code for Sentry's internal Protobuf definitions. It encapsulates the data structures used across various Sentry services, allowing Python applications to interact with Sentry's protobuf-based APIs. The library is actively maintained with frequent minor releases to incorporate new or updated protobuf schemas.","status":"active","version":"0.8.12","language":"en","source_language":"en","source_url":"https://github.com/getsentry/sentry-protos","tags":["protobuf","sentry","generated-code","serialization"],"install":[{"cmd":"pip install sentry-protos","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required runtime dependency for all generated protobuf code.","package":"protobuf","optional":false}],"imports":[{"note":"Generated protobuf modules are nested within `sentry_protos` by service and version.","wrong":"import snuba_pb2","symbol":"snuba_pb2","correct":"from sentry_protos.snuba.v1 import snuba_pb2"},{"note":"The exact import path depends on the specific Sentry service and protobuf version you need.","symbol":"MyMessage","correct":"from sentry_protos.some_service.vX import some_service_pb2"}],"quickstart":{"code":"from sentry_protos.snuba.v1 import snuba_pb2\n\n# Create a QueryRequest message\nquery_request = snuba_pb2.QueryRequest(\n    dataset='events',\n    query=\"MATCH (event) SELECT event.id\"\n)\n\nprint(f\"Successfully created Snuba QueryRequest:\")\nprint(f\"  Dataset: {query_request.dataset}\")\nprint(f\"  Query: {query_request.query}\")\n\n# You can also set fields dynamically\nanother_query = snuba_pb2.QueryRequest()\nanother_query.dataset = 'transactions'\nanother_query.query = 'MATCH (transaction) SELECT transaction.duration'\n\nprint(f\"\\nAnother QueryRequest: {another_query.query}\")","lang":"python","description":"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."},"warnings":[{"fix":"Pin your `sentry-protos` dependency to a specific minor version (e.g., `sentry-protos~=0.8.0`) and carefully test upgrades.","message":"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.","severity":"breaking","affected_versions":"0.x.y (all versions)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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).","error":"ModuleNotFoundError: No module named 'sentry_protos.some_service.v1.some_service_pb2'"},{"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.","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.","error":"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"}]}