diff --git a/src/docs/issue-platform.mdx b/src/docs/issue-platform.mdx index d4750de2df..ac8593e583 100644 --- a/src/docs/issue-platform.mdx +++ b/src/docs/issue-platform.mdx @@ -1,30 +1,37 @@ --- -title: "Issue Platform" +title: 'Issue Platform' --- The Issue Platform allows developers to create new issue types from arbitrary data sources. If you have data about something that you want to track via an issue, you can build it on the issue platform. For example, building profiling issues on the issue platform allowed us to turn things like “JSON decoding on the main thread” into their own issue types. To use the Issue Platform you need to: + 1. Write a Detector 2. Register an Issue Type -3. Send Occurrences to the Issue Platform +3. + Send Payloads to the Issue Platform + 4. Release ## Writing a Detector + The first step to introducing a new issue type to Sentry is to determine what type of issue you want to detect. It can be from any data stream, as long as you can produce an Occurrence representing the issue. Writing a detector is the hardest part of creating a new issue type. Refer to this guide for tips on how to write one. ## Register an Issue Type + To register a new issue type you need to subclass `GroupType` When registering the class, set the following required attributes on the class: + - `type_id`: A unique integer to identify your issue type. - `slug`: A unique slug to identify your issue type. Used to search by issue type in the issue stream - `description`: A human-readable description of your issue type. - `category`: The overall category that your issue type belongs to. You can register a category if the existing ones don't make sense for your issue type. You may also set these optional attributes: + - `released`: Whether this issue type has been released to all customers. See Releasing your issue type - `noise_config`: A `NoiseConfig` that allows you to set policy on how many times a fingerprint must occur in a period of time before an issue is created. NoiseConfig has two attributes: - `ignore_limit`: How many occurrences need to occur before we create a new issue @@ -33,6 +40,7 @@ You may also set these optional attributes: - `enable_escalation_detection`: Whether this issue type can escalate using the Escalating Issues Algorithm. By default this attribute is set to true. Here's an example issue type: + ```python @dataclass(frozen=True) class ProfileFileIOGroupType(GroupType): @@ -41,7 +49,9 @@ class ProfileFileIOGroupType(GroupType): description = "File I/O on Main Thread" category = GroupCategory.PROFILE.value ``` + and here's one with `noise_config` configured + ```python @dataclass(frozen=True) class ProfileFileIOGroupType(GroupType): @@ -53,67 +63,92 @@ class ProfileFileIOGroupType(GroupType): ``` ### Register a Category + You might also want to register a new category related to your issue type as well. This allows you to group related issue types together. To do so, add your category to this enum -## Send Occurrence or Status Change Payloads to the Issue Platform +## Send Payloads to the Issue Platform + If operating within the Sentry codebase, you can call sentry.issues.produce_occurrence_to_kafka with the following optional parameters: + - `payload_type`: PayloadType -- `occurrence`: IssueOccurrence -- `status_change`: StatusChangeMessage +- one of the following, per `payload_type` + - `occurrence`: IssueOccurrence + - `status_change`: StatusChange - `event_data`: Dict[str, Any] - If operating from an external service then pass a json payload that matches the Issue Occurrence Schema to the `ingest-occurrences` topic on the issue occurrences Kafka cluster -### Issue Occurrence Schema: -Schema +### Payload Type + +Determines the type of payload sent to the issue platform. By default, `payload_type` is set to `OCCURRENCE`. + +The PayloadType enum has two types: + +- `OCCURRENCE`: for sending an occurrence +- `STATUS_CHANGE`: for sending a status update + +### Issue Occurrence Schema + + + Schema + Required: + - `id`: str. A user generated uuid in string format representing a unique id for this occurrence. -Generally it's a good idea to generate this separately to your event id. + Generally it's a good idea to generate this separately to your event id. - `project_id`: int. Id of the project this occurred in -- `fingerprint`: Sequence[str]. Unique identifier for the root cause of this problem. -Used for aggregating occurrences together into groups. We only make use of the first -fingerprint for the moment - if you have a use case for additional fingerprints let the -issue platform team know. +- `fingerprint`: Sequence[str]. Unique identifier for the root cause of this problem. + Used for aggregating occurrences together into groups. We only make use of the first + fingerprint for the moment - if you have a use case for additional fingerprints let the + issue platform team know. - `issue_title`: str. A short description of the problem. This will be used as the title -of the issue and also used in notifications. + of the issue and also used in notifications. - `subtitle`: str: Extra detail about the issue, displayed below the `issue_title` - `culprit`: str: Where the problem occurred. This could be an api path, a function path, etc. -![issue properties](img/issueProperties.jpg) + ![issue properties](img/issueProperties.jpg) - `evidence_data`: Mapping[str, Any]. An arbitrary map of data. The issue platform doesn't -make use of this data directly, it just make it available for use on the frontend and in -notifications. This can be used to customize the issue details ui, notifications and so on. + make use of this data directly, it just make it available for use on the frontend and in + notifications. This can be used to customize the issue details ui, notifications and so on. - `evidence_display`: Sequence[IssueEvidence]. A sequence of `IssueEvidence` entries. These are used to display generic information about your issue in the issue details ui and in various notifications. Even if you are customizing the ui and email, it's recommended to include this so that we can display information correctly on all our other integrations. Typically, these will be displayed in a table when space allows. For space limited integrations we'll display one row that is labelled `important` if available. - `type`: int: The type of issue you are creating. Maps to `type_id` in your registered `GroupType`. - `detection_time`: float. A timestamp representing when the issue was detected. - `level`: str. Info\Warning\Error One of: + - `event_id`: str. The event id of an existing event, typically this would be an error or transaction id. - `event`: Event Optional: + - `resource_id`: str | None. An identifier used to link to an external system to load data. -For example, this could be an id that we use to build a link to a specific product page. + For example, this could be an id that we use to build a link to a specific product page. ### Issue Evidence Schema -Schema + + + Schema + - `name`: str. - `value`: str - `important`: bool. Whether this entry contains important data to display to the user. -One entry should be marked as important, and it will be displayed in space constrained -integrations. + One entry should be marked as important, and it will be displayed in space constrained + integrations. The most current version of this schema is documented here: ### Event Schema -Schema + + + Schema + The event schema should match the Sentry event schema. Any fields/interfaces defined here can be passed along with your event. It's best to fill in as many of these as makes sense for your issue type. There's a minimum set of fields which should be included: + - `environment` - `event_id` - `platform` @@ -123,19 +158,15 @@ There's a minimum set of fields which should be included: - `timestamp` Caveats -- Attachments will not work. If you have a need for this please contact the issues team. -### Payload Type -Determines the type of payload sent to the issue platform. By default, `payload_type` is set to `OCCURRENCE`. +- Attachments will not work. If you have a need for this please contact the issues team. -The PayloadType enum has two types: -- `OCCURRENCE`: for sending an occurrence -- `STATUS_CHANGE`: for sending a status update +### Status Change Schema -### Status Change Message -If `payload_type` is set to `STATUS_CHANGE` in `produce_occurrence_to_kafka`, `status_change` will update the status of an issue. +If `payload_type` is set to `STATUS_CHANGE`, providing a `StatusChangeMessage` will update the status of an issue. The `StatusChangeMessage` schema is as follows: + - `fingerprint`: unique identifier for the occurrence - `project_id`: int. - `new_status`: int. Uses GroupStatus enum. We currently support the following: @@ -144,10 +175,14 @@ The `StatusChangeMessage` schema is as follows: - `IGNORED` - `new_substatus`: int | None. Uses GroupSubStatus enum. We do not support the `NEW` substatus. +When providing the `new_status` and `new_substatus`, refer to the supported issue states and transitions here. + ## Releasing your issue type + The issue platform provides functionality to help release your new issue type in a controlled way. There are 3 feature flags that are used to release an issue type: + - Ingest - This controls whether we'll accept or drop issues of this type in our consumer -- Post processing - This controls whether we'll pass the issue along to post processing. If disabled, then issues will be created but no notifications will be sent. This can be helpful for testing out what issues look like before release. *Note:* Any issues created this way will not send new issue notifications after the flag is enabled, since they already exist. In the future, if there is demand we might provide a way to remove all test versions of a new issue type. +- Post processing - This controls whether we'll pass the issue along to post processing. If disabled, then issues will be created but no notifications will be sent. This can be helpful for testing out what issues look like before release. _Note:_ Any issues created this way will not send new issue notifications after the flag is enabled, since they already exist. In the future, if there is demand we might provide a way to remove all test versions of a new issue type. - UI - This controls whether the issue type will appear in the issue list and elsewhere in the ui. The flags for ingest and post processing are backed by options, and we automatically register these when the issue type is created. These options can be enabled for LA/EA/GA here