From 6ddaffa873eda762d16864a50cfa19a730f75162 Mon Sep 17 00:00:00 2001 From: Andrew Liu <159852527+aliu39@users.noreply.github.com> Date: Wed, 18 Dec 2024 19:41:24 -0800 Subject: [PATCH 1/4] feat(feedback): document new feedback envelope format and rename old format --- .../feedback-architecture.mdx | 18 ++-- .../sdk/data-model/envelope-items.mdx | 99 +++++++++++++++++-- develop-docs/sdk/expected-features/index.mdx | 2 +- 3 files changed, 99 insertions(+), 20 deletions(-) diff --git a/develop-docs/application-architecture/feedback-architecture.mdx b/develop-docs/application-architecture/feedback-architecture.mdx index 94cb24b03a6a3..af7b45e3fe4ad 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 **5** ways to create feedback in our system 😵‍💫. -(But 4 of them, related to user reports, are quite similar!) A good reference is the +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 `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](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples) created by the Replay team when adding +`NEW_FEEDBACK_ENVELOPE`: [The new format](/sdk/data-model/envelope-items/#user-feedback) 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](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback) with name/email/comments, that requires +`USER_REPORT_ENVELOPE`: [The older format](/sdk/data-model/envelope-items/#user-report) 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](https://develop.sentry.dev/issue-platform/). +saved via the [issues platform](/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 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 preferred way of sending feedback from the SDK is in [feedback envelope](/sdk/data-model/envelope-items/#user-feedback). 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](https://develop.sentry.dev/sdk/data-model/envelopes/#attachment) +to submit **at most 1 screenshot per feedback**. Attachments are another [item type](/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,9 +186,7 @@ graph TD ### Envelopes -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"`.** +User reports are also sent to Relay in envelope format, item type [user_report](/sdk/data-model/envelope-items/#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 009412e1a683d..feb59964091d6 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 +Item type `"event"`. This Item contains an error or default [event payload](/sdk/data-model/event-payloads/) encoded in JSON. **Constraints:** @@ -181,18 +181,93 @@ details. ### User Feedback -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: +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","email":"john@me.com","name":"John Me","comments":"It broke."}\n +{ + "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" + } + } +} ``` -**Attributes** +**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. + +`contact_email` + +: *String, recommended.* The email of the user. + +`name` + +: *String, optional.* The name of the user. + +`url` + +: *String, optional.* The URL of the referring webpage which 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. + +**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.** The identifier of the event or transaction. +: **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: +```json +{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"john@me.com","name":"John Me","comments":"It broke."}\n +``` + +**Payload Attributes** + +`event_id` + +: **UUID String, required.** The identifier of the associated event, ideally +an error. `email` @@ -209,14 +284,20 @@ The item contains a user feedback / user report JSON payload: **Constraints:** - This Item may occur once per Envelope. -- User Feedbacks / Reports can be ingested separately from their events. We recommended to - send them in the same 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. **Envelope Headers:** `event_id` -: **UUID String, required.** The identifier of the event or transaction. +: **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. **Additional Item Headers:** diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 6e289961777ab..47db946201eb9 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-feedback). 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-report). 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 From 9c6c32323cb7b6202cd48ec057baa434349e1fa6 Mon Sep 17 00:00:00 2001 From: Andrew Liu <159852527+aliu39@users.noreply.github.com> Date: Wed, 18 Dec 2024 19:48:04 -0800 Subject: [PATCH 2/4] Attachments note --- develop-docs/sdk/data-model/envelope-items.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index feb59964091d6..5b4e2dff9d753 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -235,6 +235,13 @@ for this item type. For other attributes, see [Event Payloads](/sdk/data-model/e : *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 **up to 1** screenshot/image with a feedback by sending an +[attachment item](/sdk/data-model/envelope-items/#attachment) with an `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. From 8ce13914ec9faf2c128473265a697cda40b484d6 Mon Sep 17 00:00:00 2001 From: Andrew Liu <159852527+aliu39@users.noreply.github.com> Date: Wed, 18 Dec 2024 19:48:55 -0800 Subject: [PATCH 3/4] Doc max message length --- develop-docs/sdk/data-model/envelope-items.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 5b4e2dff9d753..a0ce37bb93924 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -210,7 +210,8 @@ for this item type. For other attributes, see [Event Payloads](/sdk/data-model/e `message` -: **String, required.** Comments of the user, describing what happened and/or sharing feedback. +: **String, required.** Comments of the user, describing what happened and/or sharing +feedback. The max length is **4096 characters**. `contact_email` @@ -286,7 +287,7 @@ an error. `comments` -: *String, recommended.* Comments of the user about what happened. +: *String, recommended.* Comments of the user about what happened. The max length is **4096 characters**. **Constraints:** From a168612dfa054236c8608e21b47347b7d7bbde29 Mon Sep 17 00:00:00 2001 From: Andrew Liu <159852527+aliu39@users.noreply.github.com> Date: Fri, 20 Dec 2024 11:20:00 -0800 Subject: [PATCH 4/4] Review comments - rewording and rm max screenshots --- develop-docs/sdk/data-model/envelope-items.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index a0ce37bb93924..985928e67a054 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -215,16 +215,16 @@ feedback. The max length is **4096 characters**. `contact_email` -: *String, recommended.* The email of the user. +: *String, recommended.* The email of the user who submitted the feedback. `name` -: *String, optional.* The name of the user. +: *String, optional.* The name of the user who submitted the feedback. `url` -: *String, optional.* The URL of the referring webpage which may be used to search - for or set alerts on feedback. +: *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` @@ -233,20 +233,20 @@ feedback. The max length is **4096 characters**. `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. +: *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 **up to 1** screenshot/image with a feedback by sending an -[attachment item](/sdk/data-model/envelope-items/#attachment) with an `event_id` +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. +- This Item is mutually exclusive with `"transaction"` items. **Required Envelope Headers:**