From a85374ca343a41208fb9661e201d7acadd5012d4 Mon Sep 17 00:00:00 2001 From: stefanosiano Date: Wed, 9 Apr 2025 13:18:55 +0200 Subject: [PATCH 1/7] Added Feedbacks page under Telemetry with SDK processing details --- .../sdk/data-model/envelope-items.mdx | 62 +------- .../sdk/expected-features/rate-limiting.mdx | 3 +- develop-docs/sdk/telemetry/feedback.mdx | 140 ++++++++++++++++++ 3 files changed, 144 insertions(+), 61 deletions(-) create mode 100644 develop-docs/sdk/telemetry/feedback.mdx diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 31171a50a4fcb..e27ee261cf583 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -181,67 +181,9 @@ 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. +Item type `"feedback"` contains an event with a feedback context in the payload encoded in JSON. -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, optional.* The email of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. - -`name` - -: *String, optional.* The name of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. - -`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. +See the feedback documentation for the payload details. **Constraints:** diff --git a/develop-docs/sdk/expected-features/rate-limiting.mdx b/develop-docs/sdk/expected-features/rate-limiting.mdx index f2f8bbf75a2e3..a7df9bb0ac776 100644 --- a/develop-docs/sdk/expected-features/rate-limiting.mdx +++ b/develop-docs/sdk/expected-features/rate-limiting.mdx @@ -92,11 +92,12 @@ While these [data categories](https://github.com/getsentry/relay/blob/master/rel - `attachment`: Attachment bytes stored (unused for rate limiting) - `session`: Session update events - `profile`: Profiling events + - `profile_chunk`: Continuous Profiling chunks - `replay`: Session Replays + - `feedback`: User Feedbacks - `metric_bucket`: Sentry Metrics sent via the `statsd` or `metrics` items. The `namespaces` component of the *quota_limit* defines which namespace(s) will be affected. - `internal`: a sentry/system internal event[^internal] - - **Scope**: The unit / model in Sentry that quotas are enforced for. - `organization` - `project` diff --git a/develop-docs/sdk/telemetry/feedback.mdx b/develop-docs/sdk/telemetry/feedback.mdx new file mode 100644 index 0000000000000..0d81c04407663 --- /dev/null +++ b/develop-docs/sdk/telemetry/feedback.mdx @@ -0,0 +1,140 @@ +--- +title: Feedbacks +sidebar_order: 4 +--- + +This document is meant for Sentry SDK developers and maintainers of the Feedback ingestion pipeline. + +## Feedback Protocol + +Item type `"feedback"`. This Item contains an [event payload](/sdk/data-model/event-payloads/) encoded in JSON, with an additional `feedback` context object. + +## `"feedback"` Item + +### Feedback Context Attributes + +| Key | Type | Description | +| ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| message | string | Required. Comments of the user, describing what happened and/or sharing feedback. The max length is **4096 characters**. | +| contact_email | string | The email of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. | +| name | string | The name of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. | +| url | string | 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 | string | The identifier of an error event in the same project. Use this to explicitly link a related error in the feedback UI. | +| replay_id | string | The identifier of a related Session Replay in the same project. Sentry uses this ID to render a Replay clip in the feedback UI. | + +### Event Event Attributes + +For the full list of attributes, see [Event Payloads](/sdk/data-model/event-payloads/). + +| Key | Type | Description | +| -------------------------- | ------ | ------------------------------------------------ | +| timestamp | number | UNIX timestamp of the current time (in seconds). | +| event_id | string | This should be the same as `replay_id` | +| dist | string | - | +| platform | string | - | +| environment | string | - | +| release | string | - | +| user.id | string | - | +| user.username | string | - | +| user.email | string | - | +| user.ip_address | string | - | +| sdk.name | string | - | +| sdk.version | string | - | +| request.url | string | - | +| request.headers.User-Agent | string | - | + +### Example +```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" + } + } +} +``` + +### 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. + +## Full Envelope Example + +```json +{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","sent_at":"2024-03-19T15:18:27.581Z","sdk":{"name":"sentry.javascript.react","version":"7.105.0"}} +{"type":"feedback"} +{ + "event_id": "9ec79c33ec9942ab8353589fcb2e04dc", + "timestamp": "2011-05-02T17:41:36Z", + "platform": "javascript", + "level": "error", + "contexts": { + "organization": { "id": "0", "slug": "sentry" }, + "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" + } + }, + "environment": "prod", + "release": "frontend@f00", + "sdk": { + "integrations": [ + "BrowserTracing", + "BrowserProfiling", + "Replay", + "ReplayCanvas" + ], + "name": "sentry.javascript.react", + "version": "7.105.0" + }, + "tags": { + "sentry_version": "24.4.0.dev0", + }, + "user": { + "ip_address": "127.0.0.1", + "email": "admin@sentry.io", + "id": 1, + "name": "Admin" + } +} +``` + +## Feedback SDK Pipeline + +A feedback captured by capture_feedback is processed by the SDK. Note: The event can be discarded at any of the stages, at which point no further processing happens. + +### BeforeSendFeedback + +SDKs should implement a `beforeSendFeedback` callback to allow users to modify the feedback before it is sent. This callback should be similar to the existing [`beforeSend`](/sdk/expected-features/#before-send-hook) callback used for events. + +### Scope Data and Event Processors + +The scope is applied to the feedbacks, including tags, attachments, and trace context. The scope’s _event processors_ are invoked, too. + +### Rate Limiting + +[Rate limiting](/sdk/expected-features/rate-limiting/) is applied to feedbacks in the same way as it is applied to events. + +### Dropped feedback reports + +There is no sample rate for feedbacks, as they are always sampled. However, a feedback can be discarded at any of the pipeline stages. The SDK should report dropped feedbacks through [client reports](/sdk/telemetry/client-reports/). + +### Session Replay Integration + +SDKs are expected to flush the current Session Replay, if running. This ensures a meaningful replay recording exists and can be included in the `replay_id` attribute of the feedback context. From ee6ab8f0388db7cd16974596164128cf9ca3ee42 Mon Sep 17 00:00:00 2001 From: stefanosiano Date: Wed, 9 Apr 2025 13:30:37 +0200 Subject: [PATCH 2/7] Added Feedbacks page under Telemetry with SDK processing details --- develop-docs/sdk/telemetry/{feedback.mdx => feedbacks.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename develop-docs/sdk/telemetry/{feedback.mdx => feedbacks.mdx} (100%) diff --git a/develop-docs/sdk/telemetry/feedback.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx similarity index 100% rename from develop-docs/sdk/telemetry/feedback.mdx rename to develop-docs/sdk/telemetry/feedbacks.mdx From aebc618dde0086667acea6ca2bc5a290c1ce334d Mon Sep 17 00:00:00 2001 From: Stefano Date: Mon, 14 Apr 2025 12:02:06 +0200 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Alex Krawiec Co-authored-by: Andrew Liu <159852527+aliu39@users.noreply.github.com> --- develop-docs/sdk/telemetry/feedbacks.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/telemetry/feedbacks.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx index 0d81c04407663..3f98fa343f9f0 100644 --- a/develop-docs/sdk/telemetry/feedbacks.mdx +++ b/develop-docs/sdk/telemetry/feedbacks.mdx @@ -131,10 +131,10 @@ The scope is applied to the feedbacks, including tags, attachments, and trace co [Rate limiting](/sdk/expected-features/rate-limiting/) is applied to feedbacks in the same way as it is applied to events. -### Dropped feedback reports +### Dropped Feedback Reports -There is no sample rate for feedbacks, as they are always sampled. However, a feedback can be discarded at any of the pipeline stages. The SDK should report dropped feedbacks through [client reports](/sdk/telemetry/client-reports/). +There is no sample rate for feedbacks, as they are always sampled. However, a feedback can be discarded at any of the pipeline stages, for reasons like rate limiting or an invalid message (too large or empty). The SDK should report dropped feedbacks through [client reports](/sdk/telemetry/client-reports/). ### Session Replay Integration -SDKs are expected to flush the current Session Replay, if running. This ensures a meaningful replay recording exists and can be included in the `replay_id` attribute of the feedback context. +When sending feedback, SDKs are expected to flush the current Session Replay, if running. This ensures a meaningful replay recording exists and can be included in the `replay_id` attribute of the feedback context. From c0572841950471bb975ae99d8f073e0d5cb6d460 Mon Sep 17 00:00:00 2001 From: Stefano Date: Mon, 14 Apr 2025 12:06:49 +0200 Subject: [PATCH 4/7] Update develop-docs/sdk/telemetry/feedbacks.mdx Co-authored-by: Andrew Liu <159852527+aliu39@users.noreply.github.com> --- develop-docs/sdk/telemetry/feedbacks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/feedbacks.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx index 3f98fa343f9f0..ed43906fc98b0 100644 --- a/develop-docs/sdk/telemetry/feedbacks.mdx +++ b/develop-docs/sdk/telemetry/feedbacks.mdx @@ -22,7 +22,7 @@ Item type `"feedback"`. This Item contains an [event payload](/sdk/data-model/ev | associated_event_id | string | The identifier of an error event in the same project. Use this to explicitly link a related error in the feedback UI. | | replay_id | string | The identifier of a related Session Replay in the same project. Sentry uses this ID to render a Replay clip in the feedback UI. | -### Event Event Attributes +### Event Attributes For the full list of attributes, see [Event Payloads](/sdk/data-model/event-payloads/). From 9808d21b682689933c2c95b758b48c267afbeab9 Mon Sep 17 00:00:00 2001 From: stefanosiano Date: Mon, 14 Apr 2025 12:28:57 +0200 Subject: [PATCH 5/7] updated user email and name in example envelope --- develop-docs/sdk/telemetry/feedbacks.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/telemetry/feedbacks.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx index 0d81c04407663..3e5f5332e66b0 100644 --- a/develop-docs/sdk/telemetry/feedbacks.mdx +++ b/develop-docs/sdk/telemetry/feedbacks.mdx @@ -108,9 +108,9 @@ Envelope. }, "user": { "ip_address": "127.0.0.1", - "email": "admin@sentry.io", + "email": "john@example.com", "id": 1, - "name": "Admin" + "name": "John Smith" } } ``` From dbf5d995a84e6aac451c5740dc97e9f541340181 Mon Sep 17 00:00:00 2001 From: stefanosiano Date: Mon, 14 Apr 2025 12:52:54 +0200 Subject: [PATCH 6/7] updated required Event attributes specified SDK doesn't have to fill name and email with user context, as it's done by backend updated scope data to apply to feedbacks --- develop-docs/sdk/telemetry/feedbacks.mdx | 31 ++++++++---------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/develop-docs/sdk/telemetry/feedbacks.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx index c7c096bb0031d..f7088370f9075 100644 --- a/develop-docs/sdk/telemetry/feedbacks.mdx +++ b/develop-docs/sdk/telemetry/feedbacks.mdx @@ -16,32 +16,22 @@ Item type `"feedback"`. This Item contains an [event payload](/sdk/data-model/ev | Key | Type | Description | | ---------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | message | string | Required. Comments of the user, describing what happened and/or sharing feedback. The max length is **4096 characters**. | -| contact_email | string | The email of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. | -| name | string | The name of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. | +| contact_email | string | The email of the user who submitted the feedback. If excluded, Sentry (not the SDK) attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. | +| name | string | The name of the user who submitted the feedback. If excluded, Sentry (not the SDK) attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. | | url | string | 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 | string | The identifier of an error event in the same project. Use this to explicitly link a related error in the feedback UI. | | replay_id | string | The identifier of a related Session Replay in the same project. Sentry uses this ID to render a Replay clip in the feedback UI. | ### Event Attributes +Below is a recap of the [required attributes](/sdk/data-model/event-payloads/#required-attributes) for the event payload. For the full list of attributes, see [Event Payloads](/sdk/data-model/event-payloads/). -| Key | Type | Description | -| -------------------------- | ------ | ------------------------------------------------ | -| timestamp | number | UNIX timestamp of the current time (in seconds). | -| event_id | string | This should be the same as `replay_id` | -| dist | string | - | -| platform | string | - | -| environment | string | - | -| release | string | - | -| user.id | string | - | -| user.username | string | - | -| user.email | string | - | -| user.ip_address | string | - | -| sdk.name | string | - | -| sdk.version | string | - | -| request.url | string | - | -| request.headers.User-Agent | string | - | +| Key | Type | Description | +| -------------------------- | ------ | ----------------------------------------------- | +| timestamp | number | UNIX timestamp of the current time (in seconds) | +| event_id | string | Hexadecimal string representing a uuid4 value | +| platform | string | | ### Example ```json @@ -49,7 +39,6 @@ For the full list of attributes, see [Event Payloads](/sdk/data-model/event-payl "event_id": "9ec79c33ec9942ab8353589fcb2e04dc", "timestamp": "2011-05-02T17:41:36Z", "platform": "javascript", - "level": "error", "contexts": { "feedback": { "contact_email": "john@example.com", @@ -79,7 +68,6 @@ Envelope. "event_id": "9ec79c33ec9942ab8353589fcb2e04dc", "timestamp": "2011-05-02T17:41:36Z", "platform": "javascript", - "level": "error", "contexts": { "organization": { "id": "0", "slug": "sentry" }, "feedback": { @@ -91,6 +79,7 @@ Envelope. "replay_id":"82840977e85b4ed3bc27f7b5b25cec15" } }, + "level": "error", "environment": "prod", "release": "frontend@f00", "sdk": { @@ -125,7 +114,7 @@ SDKs should implement a `beforeSendFeedback` callback to allow users to modify t ### Scope Data and Event Processors -The scope is applied to the feedbacks, including tags, attachments, and trace context. The scope’s _event processors_ are invoked, too. +The scope is applied to the feedbacks, including tags, user, trace and contexts. The scope’s _event processors_ are invoked, too. ### Rate Limiting From b4b905db819067090c3a6f5b28960a755db83da3 Mon Sep 17 00:00:00 2001 From: Stefano Date: Tue, 15 Apr 2025 12:30:02 +0200 Subject: [PATCH 7/7] Update develop-docs/sdk/telemetry/feedbacks.mdx Co-authored-by: Andrew Liu <159852527+aliu39@users.noreply.github.com> --- develop-docs/sdk/telemetry/feedbacks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/feedbacks.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx index f7088370f9075..38388e2d99d94 100644 --- a/develop-docs/sdk/telemetry/feedbacks.mdx +++ b/develop-docs/sdk/telemetry/feedbacks.mdx @@ -31,7 +31,7 @@ For the full list of attributes, see [Event Payloads](/sdk/data-model/event-payl | -------------------------- | ------ | ----------------------------------------------- | | timestamp | number | UNIX timestamp of the current time (in seconds) | | event_id | string | Hexadecimal string representing a uuid4 value | -| platform | string | | +| platform | string | Platform of the SDK | ### Example ```json