Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(feedback): document new feedback envelope format and rename old format #12188

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
+108 −21
Open

feat(feedback): document new feedback envelope format and rename old format #12188

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6ddaffa
feat(feedback): document new feedback envelope format and rename old …
aliu39 Dec 19, 2024
9c6c323
Attachments note
aliu39 Dec 19, 2024
8ce1391
Doc max message length
aliu39 Dec 19, 2024
a168612
Review comments - rewording and rm max screenshots
aliu39 Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 8 additions & 10 deletions develop-docs/application-architecture/feedback-architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand All @@ -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

Expand All @@ -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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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`.

Expand Down
109 changes: 99 additions & 10 deletions develop-docs/sdk/data-model/envelope-items.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand Down Expand Up @@ -181,18 +181,101 @@ 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":"[email protected]","name":"John Me","comments":"It broke."}\n
{
"event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
"timestamp": "2011-05-02T17:41:36Z",
"platform": "javascript",
"level": "error",
"contexts": {
"feedback": {
"contact_email": "[email protected]",
"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. The max length is **4096 characters**.

`contact_email`

: *String, recommended.* The email of the user.
aliu39 marked this conversation as resolved.
Show resolved Hide resolved

`name`

: *String, optional.* The name of the user.
aliu39 marked this conversation as resolved.
Show resolved Hide resolved

`url`

: *String, optional.* The URL of the referring webpage which may be used to search
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"referring webpage" is a bit unclear, could we use some more specific wording here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have suggestions?
"The URL of the webpage from which the feedback was submitted from." ?
Flows a little weird

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

URL from which the feedback was submitted?
URL of the page the user was on when the feedback was submitted?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to "The URL of the webpage the user was on when submitting feedback."

Although I like the original too. I think "referring webpage" hints at HTTP referrer, which I think this field is pretty similar to?

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
aliu39 marked this conversation as resolved.
Show resolved Hide resolved
project. Sentry uses this ID to render a replay clip in the feedback UI.
aliu39 marked this conversation as resolved.
Show resolved Hide resolved

**Attaching Screenshots:**

You can associate **up to 1** screenshot/image with a feedback by sending an
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i thought we can attach multiple screenshots?🧐

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we technically can, but the UI only displays one right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no we can display multiple!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh nice! Is there a max number?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no max i believe

[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.
- This Item is mutually exclusive with `"transaction"` Items.
aliu39 marked this conversation as resolved.
Show resolved Hide resolved

**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":"[email protected]","name":"John Me","comments":"It broke."}\n
```

**Payload Attributes**

`event_id`

: **UUID String, required.** The identifier of the associated event, ideally
an error.

`email`

Expand All @@ -204,19 +287,25 @@ The item contains a user feedback / user report JSON payload:

`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:**

- 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:**

Expand Down
2 changes: 1 addition & 1 deletion develop-docs/sdk/expected-features/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading