Merge branch 'master' into abhi-logs-sdk-developer-documentation

Author: AbhiPrasad

.github/CODEOWNERS

@@ -12,7 +12,7 @@
 # /src/wizard/android/ @getsentry/team-mobile-core
 # /src/platforms/apple/ @getsentry/team-mobile-core
 # /src/wizard/apple/ @getsentry/team-mobile-core
-# /src/platforms/flutter/ @getsentry/team-mobile-cross-platform
+# /src/platforms/dart/guides/flutter/ @getsentry/team-mobile-cross-platform
 # /src/wizard/flutter/ @getsentry/team-mobile-cross-platform
 # /src/platforms/dart/ @getsentry/team-mobile-cross-platform
 # /src/wizard/dart/ @getsentry/team-mobile-cross-platform

.github/ISSUE_TEMPLATE/issue-content-01-sdks.yml

@@ -1,6 +1,7 @@
-name: "📝 SDK Documentation"
-labels: ["Type: Content", "SDKs"]
+name: '📝 SDK Documentation'
+labels: ['Type: Content', 'SDKs']
 description: Missing, incorrect, or unclear documentation of SDKs.
+type: Improvement
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/issue-content-02-product.yml

@@ -1,6 +1,7 @@
-name: "📝 Product Documentation"
-labels: ["Type: Content", "Product"]
+name: '📝 Product Documentation'
+labels: ['Type: Content', 'Product']
 description: Missing, incorrect, or unclear documentation of product features.
+type: Improvement
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/issue-content-03-develop.yml

@@ -1,6 +1,7 @@
-name: "📝 Documentation on develop.sentry.dev"
-labels: ["Type: Content", "Develop"]
+name: '📝 Documentation on develop.sentry.dev'
+labels: ['Type: Content', 'Develop']
 description: Missing, incorrect, or unclear developer documentation.
+type: Improvement
 body:
   - type: markdown
     attributes:
@@ -35,4 +36,3 @@ body:
       value: |-
         ## Thanks 🙏
         Check our [triage docs](https://open.sentry.io/triage/) for what to expect next.
-  

.github/ISSUE_TEMPLATE/issue-platform-404.yml

@@ -1,7 +1,7 @@
-name: "💻 Docs Platform: 🔗 404 Error"
-labels: "Type: Platform,404"
+name: '💻 Docs Platform: 🔗 404 Error'
+labels: 'Type: Platform,404'
 description: Broken links, missing pages, and other 404 errors.
-
+type: Bug
 body:
   - type: textarea
     id: url

.github/ISSUE_TEMPLATE/issue-platform-bug.yml

@@ -1,5 +1,6 @@
-name: "💻 Docs Platform: 🐞 Bug"
-labels: "Type: Platform,Bug"
+name: '💻 Docs Platform: 🐞 Bug'
+labels: 'Type: Platform'
+type: Bug
 description: Problems with the technical platform of our docs.
 body:
   - type: textarea

.github/ISSUE_TEMPLATE/issue-platform-improvement.yml

@@ -1,6 +1,7 @@
-name: "💻 Docs Platform: ✨ Improvement"
-labels: "Type: Platform,Improvement"
+name: '💻 Docs Platform: ✨ Improvement'
+labels: 'Type: Platform'
 description: Ideas on how we can improve the technical capabilities of our docs platform.
+type: Improvement
 body:
   - type: textarea
     id: problem

apps/changelog/package.json

@@ -25,7 +25,7 @@
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/react-toolbar": "^1.1.0",
     "@radix-ui/themes": "^3.1.3",
-    "@sentry/nextjs": "9.3.0",
+    "@sentry/nextjs": "9.7.0-alpha.0",
     "@spotlightjs/spotlight": "^2.1.1",
     "next": "15.1.2",
     "next-auth": "^4.24.5",
@@ -68,4 +68,4 @@
     "@types/react": "npm:types-react@19.0.0-rc.1",
     "@types/react-dom": "npm:types-react-dom@19.0.0-rc.1"
   }
-}
+}

develop-docs/application-architecture/feedback-architecture.mdx

@@ -93,9 +93,8 @@ 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)
-in an envelope.
+Attachments are another [item type](/sdk/data-model/envelopes/#attachment)
+in an envelope. We use attachments for the widget’s screenshot feature.
 
 - SDK v8.0.0+, Relay v24.5.1+: Sends the feedback and attachment items in the same envelope.
 - SDK < v8, all Relay versions: Sends a separate envelope for each item.

develop-docs/development-infrastructure/analytics.mdx

@@ -4,7 +4,6 @@ description: This guide steps you through instrumenting your code with Sentry's
 sidebar_order: 90
 ---
 
-
 ## Big Query
 
 [BigQuery](https://cloud.google.com/bigquery/) is a Google data warehouse that a lot of our data calls home. This includes all our analytics data and some (not all) production data that might be of interest when joins are necessary for answering richer, more complex questions. From sentry/getsentry, our data goes through [reload](https://github.com/getsentry/reload), our ETL for BigQuery.
@@ -103,6 +102,7 @@ analytics.record(
 Run the tests that touch the endpoint to ensure everything is Gucci.
 
 ### Step 3:
+
 By default, a new event type is aggregated and sent to Amplitude as long as there is a user_id sent along with the event. If you would like to send events unaggregated, refer to [our Amplitude aggregation docs](https://github.com/getsentry/etl/blob/master/documentation/amplitude_analytics.md)
 
 ## Route-Based Frontend Analytics
@@ -180,7 +180,7 @@ Example:
 <RestartButton
   analyticsEventName="Growth: Guided Tour Restart"
   analyticsEventKey="growth.guided_tour_restart"
-  analyticsParams={{tour: 'issues'}}
+  analyticsParams={{ tour: "issues" }}
 />
 ```
 
@@ -198,10 +198,10 @@ First, add the Typescript definition of the event to an analytics event file ins
 
 ```tsx
 export type ExampleTutorialEventParameters = {
-  'example_tutorial.created': {
+  "example_tutorial.created": {
     source: string;
   };
-  'example_tutorial.viewed': {
+  "example_tutorial.viewed": {
     source: string;
   };
 };
@@ -214,8 +214,8 @@ export const exampleTutorialEventMap: Record<
   keyof ExampleTutorialEventParameters,
   string | null
 > = {
-  'example_tutorial.created': 'Example Tutorial Created',
-  'example_tutorial.viewed': null, // don't send to Amplitude
+  "example_tutorial.created": "Example Tutorial Created",
+  "example_tutorial.viewed": null, // don't send to Amplitude
 };
 ```
 
@@ -242,21 +242,23 @@ Our current naming convention for Reload events is `descriptor.action` e.g. what
 
 ### Testing your Analytics Event
 
+It's important to test analytic events to ensure the data you are looking at is accurate. Any additional analytic event should be tested before merging to make sure that the events are firing correctly (with the correct values at the right times). A common issue we see when testing gets overlooked is events firing multiple times when they should only fire once.
+
 When developing locally, analytics events will not be sent to Reload or Amplitude. To test to see if your event is sending as expected and with the correct data, you can set "DEBUG_ANALYTICS" to "1" in local storage on your browser. Then it will log the analytics event data to your console, whenever it would've sent an analytics event, allowing to check your analytics locally.
 
 **getsentry**
 
 ```jsx
-import React from 'react';
+import React from "react";
 
-import { trackAnalytics } from 'getsentry/utils/analytics';
+import { trackAnalytics } from "getsentry/utils/analytics";
 
 class ExampleComponent extends React.Component {
   componentDidMount() {
-    trackAnalytics('example_tutorial.created', {
+    trackAnalytics("example_tutorial.created", {
       organization,
       subscription,
-      source: 'wakanda',
+      source: "wakanda",
     });
   }
 
@@ -271,15 +273,15 @@ class ExampleComponent extends React.Component {
 All you'll actually need is to import analytics from utils and call it wherever you need. Keep in mind the effect of React lifecycles on your data. In this case, we only want to send one event when the component mounts so we place it in `componentDidMount` .
 
 ```jsx
-import React from 'react';
+import React from "react";
 
-import { trackAnalytics } from 'getsentry/utils/analytics';
+import { trackAnalytics } from "getsentry/utils/analytics";
 
 class ExampleComponent extends React.Component {
   componentDidMount() {
-    trackAnalytics('example_tutorial.deleted', {
+    trackAnalytics("example_tutorial.deleted", {
       organization,
-      source: 'wakanda',
+      source: "wakanda",
     });
   }
   render() {
@@ -288,6 +290,18 @@ class ExampleComponent extends React.Component {
 }
 ```
 
+After deploying your changes, you can open the Dev Tools in your browser and in the "Network" tab, search for the `event/` request. This will show the events being sent to Reload and Amplitude.
+
+## Debugging
+
+If your analytics aren't showing up after you added it, you can't find an event you expect to be there, or something else goes wrong, there are a few troubleshooting steps you can try:
+
+- Follow the steps [above](https://docs.sentry.io/development-infrastructure/analytics/#testing-your-analytics-event) to confirm that your analytics event is sending correctly, with the correct parameters.
+- Check Amplitude for blocked events: In Amplitude, go to the "Data" section in the sidebar. From there, navigate to "Events" and search for your event name. It will show up with status "Blocked" if blocked, which means events won't show up. Some events may be blocked in favor of automatic route or button analytics.
+- For route analytics, confirm that the analytic event isn't being blocked with `useDisableRouteAnalytics`. Some components already had an analytic event so the route analytics were disabled.
+- Check the types of the data you are sending. Arrays aren't recommended data types to send (they can be hard to query and produce some unexpected behavior). Try to remove those if you are using them.
+- Remember there will always be some discrepency. Ad-blockers, for example, can block events from being sent. This could be a cause of why some numbers aren't adding up.
+
 ## Metrics
 
 Track aggregrate stats with [Metrics](/backend/metrics/). For example, this can be used to track aggregate response codes for an endpoint.

develop-docs/frontend/index.mdx

@@ -4,11 +4,13 @@ description: How we write frontend code at Sentry.
 sidebar_order: 60
 ---
 
-This guide specifically focuses on the frontend part of the [Sentry](https://github.com/getsentry/sentry) and [Getsentry](https://github.com/getsentry/getsentry) codebases. It assumes you are using the eslint rules outlined by [eslint-config-sentry](https://github.com/getsentry/eslint-config-sentry); hence code style enforced by these linting rules will not be discussed here.
+This guide specifically focuses on the frontend part of the [Sentry](https://github.com/getsentry/sentry).
 
 ## Directory structure
 
-The frontend codebase is currently located under `static/app` in sentry and `static/getsentry` in getsentry.
+The frontend codebase is currently located under `static/app`.
+
+As of March 2025 `static/gsApp` and `static/gsAdmin` have been open-sourced and merged into [Sentry](https://github.com/getsentry/sentry). If you are looking for earlier git history of those folders you need to have access to [Getsentry](https://github.com/getsentry/getsentry).
 
 ## Folder & File structure
 

develop-docs/frontend/network-requests.mdx

@@ -142,7 +142,7 @@ Reusable queries like this can be placed in `/sentry/actionsCreators`.
 There are many situations where your query data becomes out of date and needs to be updated or refetched. This is usually because of some user input (e.g. creating/deleting/editing a record). If you already know what the new data should look like, you can (and should) immediately update the cache using the query client:
 
 ```tsx
-import {setQueryData, queryClient} from 'utils/queryClient'
+import {setQueryData, useQueryClient} from 'utils/queryClient'
 
 const queryClient = useQueryClient();
 

develop-docs/sdk/data-model/event-payloads/exception.mdx

@@ -111,6 +111,14 @@ the root exception (the last to be listed in the exception values).
 
 : An optional flag indicating that this exception is part of an exception group type specific to the platform or language.
 
+`source`
+
+: An optional string value describing the source of the exception. The SDK should populate this with the name of the property or attribute of the parent exception that this exception was acquired from. In the case of an array, it should include the zero-based array index as well.
+
+- Python Examples: `"__context__"`, `"__cause__"`, `"exceptions[0]"`, `"exceptions[1]"`
+- .NET Examples: `"InnerException"`, `"InnerExceptions[0]"`, `"InnerExceptions[1]"`
+- JavaScript Examples: `"cause"`, `"errors[0]"`, `"errors[1]"`
+
 `meta`
 
 : Optional information from the operating system or runtime on the exception

develop-docs/sdk/data-model/event-payloads/index.mdx

@@ -304,12 +304,7 @@ Fingerprints](https://docs.sentry.io/data-management/event-grouping/).
 ## Size Limits
 
 Event ingestion imposes limits on the size of events.
-These limits are subject to future change and defined currently as:
-
-- *1MB* decompressed (and `200KB` compressed) for events of type `error`
-- *1MB* decompressed (and `200KB` compressed) for events of type `transaction`
-
-Sessions, client reports, replays, check-ins, and profiles are not events and have different size limits. See [Envelope Size Limits](/sdk/data-model/envelopes/#size-limits).
+See [Envelope Size Limits](/sdk/data-model/envelopes/#size-limits) for futher details.
 
 ## Core Interfaces
 

develop-docs/sdk/data-model/event-payloads/message.mdx

@@ -14,14 +14,16 @@ help to group similar messages into the same issue.
 : **Required**. The fully formatted message. If missing, Sentry will try to
   interpolate the message.
 
-  It must not exceed 8192 characters. Longer messages will be truncated. Sentry
-  also accepts a message where this is not set to support legacy SDKs.
+  A limit of 8192 characters is exposed in Relay and longer messages will be truncated. 
+  SDKs should not enforce this limit.
+  Sentry also accepts a message where this is not set to support legacy SDKs.
 
 `message`
 
 : _Optional_. The raw message string (uninterpolated).
 
-  It must not exceed 8192 characters. Longer messages will be truncated.
+  A limit of 8192 characters is exposed in Relay and longer messages will be truncated.
+  SDKs should not enforce this limit.
 
 `params`
 

develop-docs/sdk/overview.mdx

@@ -294,6 +294,8 @@ happens immediately that may result in a different response code (and message).
 
 ## Handling Errors
 
+### Server Errors
+
 We **highly encourage** that your SDK handle failures from the Sentry server
 gracefully. Specifically, SDKs must honor the `429` status code and not attempt
 sending until the `Retry-After` kicks in. SDKs should drop events if Sentry is
@@ -328,6 +330,20 @@ Retrying too often may cause further rate limiting or blocking by the Sentry
 server.
 </Alert>
 
+### SDK Errors
+
+We try our best to make our SDKs error-free. We are an exception monitoring service after all
+and throwing our own exceptions is awkward. However, if our SDKs do throw exceptions, we have to make
+sure we swallow them gracefully and emit an error level log describing the failure.
+
+As a **design principle**, we never capture Sentry events for exceptions happening within our SDKs, including within user-defined callbacks and hooks such as `before_send` or `traces_sampler`.
+
+The reason we avoid capturing internal SDK exceptions is that we are already in an event capturing flow
+where the scope has been applied and capturing another event at that point in the lifecycle
+would lead to undefined behavior. In the worst case, we could create a busy loop of creating and sending events repeatedly until the system crashes.
+
+In mobile SDKs, unhandled crashes will still make it to Sentry via the crash handlers. See [SDK Crash Detection](https://github.com/getsentry/sentry/tree/master/src/sentry/utils/sdk_crashes#sdk-crash-detection) for more details.
+
 ## Concurrency (Scope and Hubs)
 
 SDKs are supposed to provide standardized concurrency handling through the