Merge branch 'master' into ab/supabase-integration

Author: cleptric

.github/workflows/lint-404s.yml

@@ -7,7 +7,7 @@ on:
     branches: [master]
 
 jobs:
-  index:
+  lint-404:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

develop-docs/sdk/telemetry/spans/span-api.mdx

@@ -0,0 +1,143 @@
+---
+title: Span API
+---
+
+<Alert level="info">
+  This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. 
+</Alert>
+
+<Alert level="info">
+  The APIs specified in this document MUST be implemented by all SDKs that don't use OpenTelemetry as their underlying tracing implementation.
+  SDKs using OTel SHOULD follow their own already established span APIs but MAY orient themselves on this document if applicable.
+</Alert>
+
+Spans are measuring the duration of certain operations in an application.
+
+The topmost member of a (distributed) span tree is called the "Root Span". 
+This span has no parent span and groups together its children with a representative name for the entire operation, such as `GET /` in case of a request to a backend application.
+
+The topmost span within a service boundary is called the "Segment Span". 
+Segment spans have a `parent_span_id` pointing to a "remote" span from the parent service. 
+
+For example, a distributed trace from backend to frontend, would have a segment span for the backend, and a segment span for the frontend.
+The frontend segment span is also the root span of the entire span tree. 
+
+SDKs MUST NOT expose names like "segment span" (e.g. in APIs) to users and SHOULD NOT (read "avoid") exposing "root span" if possible.
+
+## Span Interface
+
+SDKs' span implementations MUST at minimum implement the following span interface.
+
+```ts
+interface Span {
+  private _spanId: string;
+	
+  end(endTimestamp?: SpanTimeInput): void;
+
+  setAttribute(key: string, value: SpanAttributeValue | undefined): this;
+  setAttributes(attributes: SpanAttributes): this;
+
+  setStatus(status: 'ok' | 'error'): this;
+
+  setName(name: string): this;
+
+  addLink(link: SpanLink): this;
+  addLinks(links: SpanLink[]): this;
+  
+  getName(): string;
+  getAttributes(): Record<string, SpanAttributeValue>
+}
+```
+
+When implementing the span interface, consider the following guidelines:
+
+- SDKs MAY implement additional APIs, such as getters/setters for properties (e.g. `span.getStatus()`), or additional methods for convenience (e.g. `Span::spanContext()`). 
+- SDK implementers SHOULD disallow direct mutation (without setters) of span properties such as the span name, depending on the platform and the challenges involved.
+- SDK implementers MAY disallow direct read access to span properties, depending on the platform and the challenges involved.
+
+## Span Starting APIs
+
+SDKs MUST expose at least one API to start a span. SDKs MAY expose additional APIs, depending on the platform, language conventions and requirements.
+
+### Default `startSpan` API
+
+SDKs MUST expose a default `startSpan` API that takes options and returns a span:
+
+```ts
+function startSpan(options: StartSpanOptions): Span;
+
+interface StartSpanOptions {
+  name: string;
+  attributes?: Record<string, SpanAttributeValue>;
+  parentSpan?: Span | null;
+  active?: boolean;
+}
+```
+
+SDKs MUST allow specifying the following options to be passed to `startSpan`:
+
+| Option        | Required | Description                                  |
+|---------------|----------|----------------------------------------------|
+| `name`        | Yes      | The name of the span. MUST be set by users   |
+| `attributes`  | No       | Attributes to attach to the span.            |
+| `parentSpan`  | No       | The parent span. See description below for implications of allowed values |
+| `active`      | No       | Whether the started span should be _active_ (i.e. if spans started while this span is active should become children of the started span). |
+
+Behaviour:
+- Spans MUST be started as active by default. This means that any span started, while the initial span is active, MUST be attached as a child span of the active span. 
+- Only if users set `active: false`, the span will be started as inactive, meaning spans started while this span is not yet ended, will not become children, but siblings of the started span.
+- If a `Span` is passed via `parentSpan`, the span will be started as the child of the passed parent span. This has precedence over the currently active span.
+- If `null` is passed via `parentSpan`, the new span will be started as a root/segment span.
+- SDKs MUST NOT end the span automatically. This is the responsibility of the user.
+- `startSpan` MUST always return a span instance, even if the started span's trace is negatively sampled.
+
+
+### Additional Span Starting APIs
+
+SDKs MAY expose additional span starting APIs or variants of `startSpan` that make sense for the platform. 
+These could be decorators, annotations, or closure- or callback-based APIs. 
+Additional APIs MAY e.g. end spans automatically (for example, when a callback terminates, the span is ended automatically).
+Likewise, additional APIs MAY also adjust the span status based on errors thrown.
+
+### Explicitly creating a child span
+
+At this time, SDKs MUST NOT expose APIs like `Span::startChild` or similar functionality that explicitly creates a child span.
+This is still TBD but the `parentSpan` option should suffice to serve this use case.
+
+## Utility APIs
+
+SDKs MAY expose additional utility APIs for users, or internal usage to access certain spans. For example,
+
+- `Scope::getSpan()` - returns the currently active span.
+- `Scope::_INTERNAL_getSegmentSpan()` - returns the segment span of the currently active span (MUST NOT be documented for users)
+
+## Example
+
+```ts
+
+const checkoutSpan = Sentry.startSpan({ name: 'on-checkout-click', attributes: { 'user.id': '123' } })
+
+const validationSpan = Sentry.startSpan({ name: 'validate-shopping-cart'})
+startFormValidation().then((result) => {
+  validationSpan.setAttribute('valid-form-data', result.success);
+  processSpan.end();
+})
+
+const processSpan = Sentry.startSpan({ name: 'process-order', parentSpan: checkoutSpan});
+processOrder().then((result) => {
+  processSpan.setAttribute('order-processed', result.success);
+  processSpan.end();
+}).catch((error) => {
+  processSpan.setStatus('error');
+  processSpan.setAttribute('error', error.message);
+  processSpan.end();
+});
+
+const unrelatedSpan = Sentry.startSpan({ name: 'log-order', parentSpan: null});
+logOrder()
+unrelatedSpan.end();
+
+on('checkout-finished', ({ timestamp }) => {
+	checkoutSpan.end(timestamp);
+})
+```

develop-docs/sdk/telemetry/spans/span-trace-propagation.mdx

@@ -0,0 +1,28 @@
+---
+title: Span Trace Propagation
+---
+
+<Alert level="info">
+  This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.
+</Alert>
+
+## Continue an incoming trace
+
+To continue a trace from an upstream service, the SDK must expose a method to extract the traceparent and baggage information and apply these to the applicable scope.
+
+```js
+scope.setPropagationContext({
+    traceparent: request.headers.SENTRY_TRACE,
+    baggage: request.headers.SENTRY_BAGGAGE,
+})
+```
+Newly created root spans should now contain these properties, such as `trace_id` and `parent_span_id`.
+
+## Continue an outgoing trace
+
+To propagate a trace to a downstream service, the SDK must expose methods to fetch the required information to allow the next service to continue the trace.
+
+```js
+traceparent = scope.getTraceparent()
+baggage = scope.getBaggage()
+```

docs/platforms/dart/guides/flutter/troubleshooting.mdx

@@ -57,7 +57,7 @@ This happens because Dart's async/await implementation can cause stack trace inf
 ### What Can You Do?
 
 In order to get better debugging information for these cases you can:
-- Add relevant context to your Sentry events using [custom tags](/platforms/dart/guides/flutter/data-management/tags/) and [breadcrumbs](/platforms/dart/guides/flutter/data-management/breadcrumbs/) for critical paths in your application
+- Add relevant context to your Sentry events using [custom tags](/platforms/dart/guides/flutter/enriching-events/tags/) and [breadcrumbs](/platforms/dart/guides/flutter/enriching-events/breadcrumbs/) for critical paths in your application
 - Consider using [Sentry's Structured Logs](/platforms/dart/logs/) to capture additional debugging data alongside your errors
 
 ## Support 16 KB Page Sizes on Android

docs/platforms/javascript/guides/aws-lambda/install/cjs-npm__v9.x.mdx

@@ -11,7 +11,7 @@ In this guide you will learn how to set up the `@sentry/aws-serverless` SDK for
 We recommend starting the SDK automatically via environment variables so that you only have to make minimal code changes to your lambda function.
 If you need more control over the SDK setup, you can also [initialize the SDK in in code](#alternative-initialize-the-sdk-in-code).
 
-However, you need to modify your code and deploy the Sentry dependencies alongside your function code. If you're looking for the most simple way to set up Sentry, you might want to use the [Lambda Layer](./layer__v9.x) instead.
+However, you need to modify your code and deploy the Sentry dependencies alongside your function code. If you're looking for the most simple way to set up Sentry, you might want to use the [Lambda Layer](./layer__v9.x.mdx) instead.
 
 ## 1. Prerequisites
 

docs/platforms/javascript/guides/aws-lambda/install/index__v9.x.mdx

@@ -18,11 +18,11 @@ Note that TypeScript can also be configured to output ESM, in which case you sho
 
 ### My Lambda function uses `require`
 
-If you are using `require()` in your function, follow the CommonJS instructions. Choose between [using our Lambda Layer (recommended)](./install/layer__v9.x) or [installing the Sentry AWS NPM package](./install/npm__v9.x).
+If you are using `require()` in your function, follow the CommonJS instructions. Choose between [using our Lambda Layer (recommended)](./install/layer__v9.x.mdx) or [installing the Sentry AWS NPM package](./install/npm__v9.x.mdx).
 
 ### My Lambda function uses `import`
 
-If you're using `import` syntax in your function and you're _not_ transpiling the code to CommonJS, follow the [ESM instructions](./install/esm-npm__v9.x).
+If you're using `import` syntax in your function and you're _not_ transpiling the code to CommonJS, follow the [ESM instructions](./install/esm-npm__v9.x.mdx).
 
 ### Can I use the Lambda layer for ESM functions?
 

docs/platforms/javascript/guides/aws-lambda/install/layer__v8.x.mdx

@@ -8,13 +8,13 @@ noindex: true
 og_image: /og-images/platforms-javascript-guides-aws-lambda-install-layer__v8.x.png
 ---
 
-The easiest way to get started with Sentry is to use the Sentry [Lambda Layer](https://docs.aws.amazon.com/Lambda/latest/dg/configuration-layers.html) instead of adding `@sentry/aws-serverless` with `npm` or `yarn` [manually](../install/npm).
+The easiest way to get started with Sentry is to use the Sentry [Lambda Layer](https://docs.aws.amazon.com/Lambda/latest/dg/configuration-layers.html) instead of adding `@sentry/aws-serverless` with `npm` or `yarn` [manually](../install/npm.mdx).
 If you follow this guide, you don't have to worry about deploying Sentry dependencies alongside your function code.
 To actually start the SDK, you can decide between setting up the SDK using environment variables or in your Lambda function code. We recommend using environment variables as it's the easiest way to get started. [Initializing the SDK in code](#alternative-initialize-the-sdk-in-code) instead of setting environment variables gives you more control over the SDK setup if you need it.
 
 <Alert>
 
-This installation method **does not** work with Lambda functions running in EcmaScript Modules (ESM) mode, using `import` syntax. If you're running your function in ESM, follow the [ESM guide](../install/npm).
+This installation method **does not** work with Lambda functions running in EcmaScript Modules (ESM) mode, using `import` syntax. If you're running your function in ESM, follow the [ESM guide](../install/npm.mdx).
 
 </Alert>
 

docs/platforms/javascript/guides/aws-lambda/install/layer__v9.x.mdx

@@ -7,13 +7,13 @@ sidebar_order: 1
 og_image: /og-images/platforms-javascript-guides-aws-lambda-install-layer__v9.x.png
 ---
 
-The easiest way to get started with Sentry is to use the Sentry [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) instead of adding `@sentry/aws-serverless` with `npm` or `yarn` [manually](./npm__v9.x).
+The easiest way to get started with Sentry is to use the Sentry [Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/adding-layers.html) instead of adding `@sentry/aws-serverless` with `npm` or `yarn` [manually](./npm__v9.x.mdx).
 If you follow this guide, you don't have to worry about deploying Sentry dependencies alongside your function code.
 To actually start the SDK, you can decide between setting up the SDK using environment variables or in your Lambda function code. We recommend using environment variables as it's the easiest way to get started. [Initializing the SDK in code](#alternative-initialize-the-sdk-in-code) instead of setting environment variables gives you more control over the SDK setup if you need it.
 
 <Alert>
 
-This installation method **does not** work with Lambda functions running in EcmaScript Modules (ESM) mode, using `import` syntax. If you're running your function in ESM, follow the [ESM guide](../npm__v9.x).
+This installation method **does not** work with Lambda functions running in EcmaScript Modules (ESM) mode, using `import` syntax. If you're running your function in ESM, follow the [ESM guide](../npm__v9.x.mdx).
 
 </Alert>
 

docs/platforms/javascript/guides/aws-lambda/install/npm__v9.x.mdx

@@ -8,13 +8,13 @@ Based on whether your Lambda function runs in CommonJS or ESM, you need to follo
 
 ## My Lambda function is written in TypeScript
 
-If you're using TypeScript, your lambda function is likely transpiled to CommonJS before running it. In this case, follow the [CommonJS instructions](./cjs-npm__v9.x).
-Note that TypeScript can also be configured to output ESM, in which case you should follow the [ESM instructions](./esm-npm__v9.x).
+If you're using TypeScript, your lambda function is likely transpiled to CommonJS before running it. In this case, follow the [CommonJS instructions](./cjs-npm__v9.x.mdx).
+Note that TypeScript can also be configured to output ESM, in which case you should follow the [ESM instructions](./esm-npm__v9.x.mdx).
 
 ## My Lambda function uses `require`
 
-If you are using `require()` in your function, follow the [CommonJS instructions](./cjs-npm__v9.x).
+If you are using `require()` in your function, follow the [CommonJS instructions](./cjs-npm__v9.x.mdx).
 
 ## My Lambda function uses `import`
 
-If you're using `import` syntax in your function and you're _not_ transpiling the code to CommonJS, follow the [ESM instructions](./esm-npm__v9.x).
+If you're using `import` syntax in your function and you're _not_ transpiling the code to CommonJS, follow the [ESM instructions](./esm-npm__v9.x.mdx).

docs/platforms/react-native/session-replay/index.mdx

@@ -150,6 +150,33 @@ If you encounter any data not being redacted with the default settings, please l
 
 </Alert>
 
+### Screenshot Strategy (Android only)
+
+_Available in version 7.5.0 of the React Native SDK_
+
+The SDK offers two strategies for recording replays on Android: `PixelCopy` and `Canvas`.
+
+`PixelCopy` uses Android's [PixelCopy](https://developer.android.com/reference/android/view/PixelCopy) API to capture screenshots of the current screen and takes a snapshot of the view hierarchy within the same frame. The view hierarchy is then used to find the position of controls such as text boxes, images, labels, and buttons and mask them with a block that's drawn over these controls. This strategy has slightly lower performance overhead but may result in masking misalignments due to the asynchronous nature of the PixelCopy API. We recommend using this strategy for apps that do not have strict PII requirements or do not require masking functionality.
+
+`Canvas` uses Android's custom [Canvas](https://developer.android.com/reference/android/graphics/Canvas) API to redraw the screen contents onto a bitmap, masking all `drawText` and `drawBitmap` operations in the process to produce a masked screenshot. This strategy has a slightly higher performance overhead but provides more reliable masking. We recommend using this strategy for apps with strict PII requirements.
+
+<Alert level="warning">
+
+The `Canvas` screenshot strategy is currently experimental and does **not** support any masking options. When the screenshot strategy is set to `Canvas`, it will **always** mask all texts, input fields and images, disregarding any masking options set. If you need more flexibility with masking, switch back to `PixelCopy`.
+
+</Alert>
+
+You can change the strategy as follows:
+
+```javascript {tabTitle:Mobile}
+integrations: [
+  // You can pass options to the mobileReplayIntegration function during init:
+  Sentry.mobileReplayIntegration({
+    screenshotStrategy: 'canvas' // or 'pixelCopy' (default)
+  }),
+]
+```
+
 ## React Component Names
 
 Sentry helps you capture your React components and unlock additional insights in your application. You can set it up to use React component names.