From 4db7fe0137836717c768242f64aeb6dc55d4da47 Mon Sep 17 00:00:00 2001 From: Andrew Liu <159852527+aliu39@users.noreply.github.com> Date: Mon, 6 Jan 2025 11:58:14 -0800 Subject: [PATCH] =?UTF-8?q?Revert=20"feat(feedback):=20document=20new=20fe?= =?UTF-8?q?edback=20envelope=20format=20and=20rename=20old=20=E2=80=A6"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit c924f0d6617493715246b45e239cd42720c3cce6. --- .../feedback-architecture.mdx | 18 +-- .../sdk/data-model/envelope-items.mdx | 109 ++---------------- develop-docs/sdk/expected-features/index.mdx | 2 +- 3 files changed, 21 insertions(+), 108 deletions(-) diff --git a/develop-docs/application-architecture/feedback-architecture.mdx b/develop-docs/application-architecture/feedback-architecture.mdx index af7b45e3fe4ad..94cb24b03a6a3 100644 --- a/develop-docs/application-architecture/feedback-architecture.mdx +++ b/develop-docs/application-architecture/feedback-architecture.mdx @@ -11,17 +11,17 @@ It will: ## Creation sources -When broken down, there are **4** ways to create feedback in our system, with -3 sharing the same data model. A good reference is the +When broken down, there are **5** ways to create feedback in our system 😵‍💫. +(But 4 of them, related to user reports, are quite similar!) A good reference is the `FeedbackCreationSource(Enum)` in [create_feedback.py](https://github.com/getsentry/sentry/blob/2b642e149c79b251e1c2f4339fc73d656347d74e/src/sentry/feedback/usecases/create_feedback.py#L33-L33). The 4 ways _clients_ can create feedback are: -`NEW_FEEDBACK_ENVELOPE`: [The new format](/sdk/data-model/envelope-items/#user-feedback) created by the Replay team when adding +`NEW_FEEDBACK_ENVELOPE`: [The new format](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples) created by the Replay team when adding the [User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget) to the JavaScript SDK. It allows adding more information, for example tags, release, url, etc. -`USER_REPORT_ENVELOPE`: [The older format](/sdk/data-model/envelope-items/#user-report) with name/email/comments, that requires +`USER_REPORT_ENVELOPE`: [The older format](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback) with name/email/comments, that requires `event_id` to link a Sentry error event. `USER_REPORT_DJANGO_ENDPOINT`: [The deprecated Web API](https://docs.sentry.io/api/projects/submit-user-feedback/) @@ -31,7 +31,7 @@ release, url, etc. ## How feedback is stored On the backend, each feedback submission in Sentry's UI is **an un-grouped issue occurrence**, -saved via the [issues platform](/issue-platform/). +saved via the [issues platform](https://develop.sentry.dev/issue-platform/). The entrypoint is [**`create_feedback_issue()`**](https://github.com/getsentry/sentry/blob/2b642e149c79b251e1c2f4339fc73d656347d74e/src/sentry/feedback/usecases/create_feedback.py#L184-L184), which @@ -42,7 +42,7 @@ which ## Feedback events -The preferred way of sending feedback from the SDK is in [feedback envelope](/sdk/data-model/envelope-items/#user-feedback). +The new and preferred way to send feedback from the SDK is in an [event envelope](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples). The format is the same as error events, except the `type` header = `"feedback"`. While user reports have an associated event, **new feedback _is_ an event**. This offers 2 improvements: @@ -94,7 +94,7 @@ In Relay v24.5.1, we migrated feedback to its own kafka topic + consumer, ### Attachments We only use attachments for the widget’s screenshot feature, which allows users -to submit **at most 1 screenshot per feedback**. Attachments are another [item type](/sdk/data-model/envelopes/#attachment) +to submit **at most 1 screenshot per feedback**. Attachments are another [item type](https://develop.sentry.dev/sdk/data-model/envelopes/#attachment) in an envelope. - SDK v8.0.0+, Relay v24.5.1+: Sends the feedback and attachment items in the same envelope. @@ -186,7 +186,9 @@ graph TD ### Envelopes -User reports are also sent to Relay in envelope format, item type [user_report](/sdk/data-model/envelope-items/#user-report). +User reports are also sent to Relay in [envelope format](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback). +**This item type is misleadingly called “user feedback” in some of our docs, but the +item header will read `"user_report"`.** The SDK function that sends these is `captureUserFeedback`. diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 985928e67a054..009412e1a683d 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -16,7 +16,7 @@ The headers described in this section are **in addition to the common headers**. ### Event -Item type `"event"`. This Item contains an error or default [event payload](/sdk/data-model/event-payloads/) +Item type `"event"`. This Item contains an error or default event payload encoded in JSON. **Constraints:** @@ -181,101 +181,18 @@ details. ### User Feedback -Item type `"feedback"`. This Item contains an [event payload](/sdk/data-model/event-payloads/) encoded in JSON, with an additional `feedback` context object. - -Example payload: -```json -{ - "event_id": "9ec79c33ec9942ab8353589fcb2e04dc", - "timestamp": "2011-05-02T17:41:36Z", - "platform": "javascript", - "level": "error", - "contexts": { - "feedback": { - "contact_email": "john@example.com", - "name": "John Smith", - "message": "I love session replay!", - "url": "https://sentry.io/replays/", - "associated_event_id": "32fd1995636d446385016e2747623e11", - "replay_id":"82840977e85b4ed3bc27f7b5b25cec15" - } - } -} -``` - -**Payload Attributes** - -We only document attributes for the `contexts.feedback` object, which is **required** -for this item type. For other attributes, see [Event Payloads](/sdk/data-model/event-payloads/). - -`message` - -: **String, required.** Comments of the user, describing what happened and/or sharing -feedback. The max length is **4096 characters**. - -`contact_email` - -: *String, recommended.* The email of the user who submitted the feedback. - -`name` - -: *String, optional.* The name of the user who submitted the feedback. - -`url` - -: *String, optional.* The URL of the webpage the user was on when submitting feedback. - This may be used to search for or set alerts on feedback. - -`associated_event_id` - -: *UUID String, optional.* The identifier of an error event in the same project. - Use this to explicitly link a related error in the feedback UI. - -`replay_id` - -: *UUID String, optional.* The identifier of a related Session Replay in the same - project. Sentry uses this ID to render a Replay clip in the feedback UI. - -**Attaching Screenshots:** - -You can associate screenshots with a feedback by sending image data as -[attachment items](/sdk/data-model/envelope-items/#attachment), with `event_id` -corresponding to the feedback item. We recommend sending the items in the same -Envelope. - -**Constraints:** - -- This Item may occur at most once per Envelope. -- This Item is mutually exclusive with `"transaction"` items. - -**Required Envelope Headers:** - -`event_id` - -: **UUID String, required.** Corresponds to the `event_id` field of the event - payload. **It is not equal to the `associated_event_id`** field in the feedback - context. Clients are required to generate an event identifier ahead of time - and set it at least in the Envelope headers. If the identifier mismatches - between the Envelope and payload, the Envelope header takes precedence. - -### User Report - -Item type `"user_report"`. This is an older way of submitting user feedback we -are in the process of deprecating. It works by associating user information and -comments with an event. If both the item and its associated event are accepted, -we convert it to a user feedback. - -The item contains a JSON payload like this: +User Feedback was called User Report in the beginning. Therefore the envelope item type is `"user_report"`. +The item contains a user feedback / user report JSON payload: ```json {"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"john@me.com","name":"John Me","comments":"It broke."}\n ``` -**Payload Attributes** +**Attributes** `event_id` -: **UUID String, required.** The identifier of the associated event, ideally -an error. +: **UUID String, required.** The identifier of the event or transaction. + `email` @@ -287,25 +204,19 @@ an error. `comments` -: *String, recommended.* Comments of the user about what happened. The max length is **4096 characters**. +: *String, recommended.* Comments of the user about what happened. **Constraints:** - This Item may occur once per Envelope. -- User Reports can be ingested separately from their events. However, we recommend - sending them in the same Envelope. -- You may not associate multiple User Reports to the same event. -- The event can not be more than 30 minutes old. -- If the event does not exist in the same project or was never ingested, the report - is discarded and never converted to feedback. +- User Feedbacks / Reports can be ingested separately from their events. We recommended to + send them in the same Envelope. **Envelope Headers:** `event_id` -: **UUID String, required.** Corresponds to the `event_id` field of the payload. - If the identifier mismatches between the Envelope and payload, the Envelope - header takes precedence. +: **UUID String, required.** The identifier of the event or transaction. **Additional Item Headers:** diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 47db946201eb9..6e289961777ab 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -147,7 +147,7 @@ Ability to get the ID of the last event sent. Event IDs are useful for correlati ## User Feedback -For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope item](/sdk/data-model/envelope-items/#user-report). Alternatively, the SDKs can +For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope item](/sdk/data-model/envelope-items/#user-feedback). Alternatively, the SDKs can use the [User Feedback endpoint](https://docs.sentry.io/api/projects/submit-user-feedback/), which is not recommended. ### User Facing Platforms