[SDK docs] add new UF data model and implementation details under telemetry dev docs

[aliu39]

https://develop.sentry.dev/sdk/telemetry/

@AbhiPrasad :

outline:
What public API/init options an SDK should add for user feedback support
What exact scope data gets attached to user feedback. This should be split into required (stuff we need to grab from scope) and optional (sdks should try to attach this, but no big deal if they don’t)
How user feedback is rate limited and any subsequent sdk impacts
Client outcomes behaviour for user feedback (should we collect them, what is important, etc.)
It probably would help clarifying what fields on event are supported in the user feedback event payload as well. Like is it valid to attach a stacktrace onto user feedback event payloads?

https://develop.sentry.dev/sdk/telemetry/sessions/ is a good guide for this.
I recently did something similar for logs as well: https://develop-docs-git-abhi-logs-sdk-developer-documentation.sentry.dev/sdk/telemetry/logs/

Raised by @stefanosiano :

• Should UF go through eventProcessors or beforeSend callbacks?
• Implementing beforeSendFeedback hook

[stefanosiano]

Here are all the points I'd like to clarify and to be specced out:

1. Should the user feedbacks go through beforeSend callback or do we have to create a beforeSendFeedback callback?
2. Should the user feedbacks go through EventProcessors?
3. Should we apply scope data to the feedback? And which data? We have tags, attachments, trace context and current transaction
4. Should we report dropped feedbacks?
5. Is there rate limit for feedbacks?
6. Is the SDK expected to automatically capture the replay (and its id) when captureFeedback is called? Or is it something to do only with the UI widget?
7. I expect feedbacks not to be sampled, but it would be nice to confirm explicitly

[aliu39]

Hi @stefanosiano -

1. You should create a beforeSendFeedback. beforeSend is meant for errors only, according to @AbhiPrasad - https://sentry.slack.com/archives/C05J714QPRR/p1743185446086779?thread_ts=1743179617.389389&cid=C05J714QPRR

2. I'm unfamiliar with event processors, maybe someone else can help?
   But to clarify the dev docs snippet "new feedback is an event" - feedback is formatted like an event envelope, but it's its own type (not an error). All event payload required fields are also required for feedback, and the feedback context object is required. All other fields are optional.

3. Yes, we display tags, attachments, and trace context in Sentry's feedback UI. Feel free to add transaction as a tag, and it'll show up in the "tags" list in the UI. I think it'll also become searchable, but need to test it out.

4. Yes, if it's possible to emit outcomes in the SDK, we use DataCategory USER_REPORT_V2. Example.

5. Yes, in Relay and issues consumer - https://www.notion.so/sentry/User-Feedback-rate-limiting-and-filtering-3204d75381d845d6a95b149f05f3d01c?pvs=4#e8986d980b1745c3ab8350bc235d945a

6. No, the replay ID is only used to associate the feedback with a replay after ingestion. AFAIK we don't do any validation on it or reject feedback because the ID is invalid. It's up to the caller to provide a valid, same-project replay ID and capture that replay with a replay integration.

7. They aren't sampled

[getsantry]

Routing to @getsentry/product-owners-user-feedback for triage ⏲️

[jamescrosswell]

5. Yes, in Relay and issues consumer - https://www.notion.so/sentry/User-Feedback-rate-limiting-and-filtering-3204d75381d845d6a95b149f05f3d01c?pvs=4#e8986d980b1745c3ab8350bc235d945a

@aliu39 could you copy the relevant details from that Notion document back here to this issue (some of the SDKs are maintained by folks without access to Notion).

[stefanosiano]

Thanks for the replies!
Just a couple of things to clarify

1. You should create a beforeSendFeedback. beforeSend is meant for errors only, according to @AbhiPrasad - https://sentry.slack.com/archives/C05J714QPRR/p1743185446086779?thread_ts=1743179617.389389&cid=C05J714QPRR

Ok

2. I'm unfamiliar with event processors, maybe someone else can help?> But to clarify the dev docs snippet "new feedback is an event" - feedback is formatted like an event envelope, but it's its own type (not an error). All event payload required fields are also required for feedback, and the feedback context object is required. All other fields are optional.

Event Processors are components that allow to modify events and transactions. Since it's used for transactions, too, should we send feedbacks through it?

3. Yes, we display tags, attachments, and trace context in Sentry's feedback UI. Feel free to add transaction as a tag, and it'll show up in the "tags" list in the UI. I think it'll also become searchable, but need to test it out.

Ok

4. Yes, if it's possible to emit outcomes in the SDK, we use DataCategory USER_REPORT_V2. Example.

Ok

5. Yes, in Relay and issues consumer - https://www.notion.so/sentry/User-Feedback-rate-limiting-and-filtering-3204d75381d845d6a95b149f05f3d01c?pvs=4#e8986d980b1745c3ab8350bc235d945a

I cannot find the key we should listen in the SDK to limit the feedbacks. Can you post it here, please?

6. No, the replay ID is only used to associate the feedback with a replay after ingestion. AFAIK we don't do any validation on it or reject feedback because the ID is invalid. It's up to the caller to provide a valid, same-project replay ID and capture that replay with a replay integration.

Let me rephrase it. We want to capture the replay that caused the user to send the feedback.
With the feedback UI widget we take up to 30 seconds before opening the widget and add it when the feedback is sent, since we buffer the replay in chunks of 30 seconds.
Do we want to do the same for the raw API?
I mean, do we want to ensure that the replay is finished right before the feedback is sent, so that we have up to 30 seconds of replay ending when the feedback is sent?
Otherwise we may have an "older" replay that ends up to 30 seconds before the feedback is sent

7. They aren't sampled

Ok

[AbhiPrasad]

I cannot find the key we should listen in the SDK to limit the feedbacks. Can you post it here, please?

https://github.com/getsentry/relay/blob/9f4f27c9f1d7eb8c957841c6db81cc00fd2a298a/relay-base-schema/src/data_category.rs#L187

This should be feedback

[aliu39]

Event Processors are components that allow to modify events and transactions. Since it's used for transactions, too, should we send feedbacks through it?

Gotcha, I'm not an expert here but I think it makes sense, especially the scope processors apply_to_event

With the feedback UI widget we take up to 30 seconds before opening the widget and add it when the feedback is sent, since we buffer the replay in chunks of 30 seconds.
Do we want to do the same for the raw API?

Oh right, you're talking about flushing the replay, right? Yes, I'd do the same thing for the API, otherwise the replay would not be ingested if it's in buffer mode.