Merge branch 'master' of github.com:getsentry/sentry-docs into smi/quick-start/nextjs

Author: inventarSarah

.vscode/settings.json

@@ -12,5 +12,8 @@
   "git.ignoreLimitWarning": true,
   "search.exclude": {
     "**/src/wizard/**": true
-  }
+  },
+  "cSpell.words": [
+    "laravel"
+  ]
 }

develop-docs/sdk/expected-features/data-handling.mdx

@@ -23,11 +23,11 @@ Some examples of data guarded by this flag:
 - On desktop applications
   - The username logged in the device is not included. This is often a person's name.
   - The machine name is not included, for example `Bruno's laptop`
-- SDKs don't set `{{auto}}` as `user.ip`. This instructs the server to keep the connection's IP address.
+- SDKs don't set `{{auto}}` as `user.ip_address`. This instructs the server to keep the connection's IP address.
 - Server SDKs remove the IP address of incoming HTTP requests.
 
 Sentry server is always aware of the connecting IP address and can use it for logging in some platforms. Namely JavaScript and iOS/macOS/tvOS.
-All other platforms require the event to include `user.ip={{auto}}` which happens if `sendDefaultPii` is set to true.
+All other platforms require the event to include `user.ip_address={{auto}}` which happens if `sendDefaultPii` is set to true.
 
 Before sending events to Sentry, the SDKs should invokes callbacks. That allows users to remove any sensitive data client-side.
 
@@ -63,12 +63,16 @@ This helps Relay to know what kind of data it receives and this helps with scrub
   If query strings are present in the URL or fragments (Browser SDKs only) are present in the URI, both are set into the data attribute of the span.
 
   ```js
-  span.setData({
+  span.setAttributes({
     "http.query": url.getQuery(),
     "http.fragment": uri.getFragment(),
   });
   ```
 
+  ```python
+  span.set_data("http.query", query)
+  ```
+
   Additionally all semantic conventions of OpenTelementry for http spans should be set in the `span.data` if applicable:
   https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/http/
 
@@ -86,7 +90,7 @@ If the `message` in a breadcrumb contains an URL it should be formatted the same
 If query strings are present in the URL or fragments (Browser SDKs only) are present in the URI, both should also be set in the data attribute like with `http` spans.
 
 ```js
-getCurrentHub().addBreadcrumb({
+Sentry.addBreadcrumb({
   type: "http",
   category: "xhr",
   data: {

develop-docs/sdk/telemetry/traces/index.mdx

@@ -228,24 +228,23 @@ A transaction's sampling decision should be passed to all of its children, inclu
 
 To improve the likelihood of capturing complete traces when backend services use a custom sample rate via `tracesSampler`, the SDK propagates the same random value used for sampling decisions across all services in a trace. This ensures consistent sampling decisions across a trace instead of generating a new random value for each service.
 
-If no `tracesSampler` callback is used, the SDK fully inherits sampling decisions for propagated traces, and the presence of `sample_rand` in the DSC doesn't affect the decision. However, this behavior may change in the future.
+The random value (`sample_rand`) is set according to the following rules:
 
-The random value is set according to the following rules:
+1. When tracing is enabled and a new trace is started, the SDK generates a `sample_rand` value for the current execution context. A `sample_rand` is a float (`0.1234` notation) in the range of `[0, 1)` (including 0.0, excluding 1.0).
+1. It is _recommended_ to generate the random number deterministically using the trace ID as seed or source of randomness. The exact method by which the random number is created is implementation defined and may vary between SDK implementations.
+1. The `sample_rand` is part of the DSC (Dynamic Sampling Context) and as with other values on the `baggage` header, the `sample_rand` value from the current execution context should be propagated to downstream SDKs.
+1. On incoming traces, an SDK takes the incoming `sentry-sample_rand` value in the `baggage` header and uses it for the rest of the current execution context (e.g. request).
+1. If `sample_rand` is missing on an incoming trace, the SDK creates a new one applying **special rules** and uses it for the current execution context:
+   1. If `sample_rate` (inside `baggage`) and the sampling decision (trailing `-1` or `-0` from the `sentry-trace` header) are present in the incoming trace, create `sample_rand` so that when compared to the incoming `sample_rate` it would lead to the same sampling decision that is in the `sentry-trace` header. This means, for a decision of `True` generate a random number in half-open range `[0, rate)` and for a decision of `False` generate a random number in range `[rate, 1)`.
+   1. If the sampling decision is missing on the incoming trace, generate a random number in range of `[0, 1)` (including 0.0, excluding 1.0), like for a new trace.
 
-1. When an SDK starts a new trace, `sample_rand` is always set to a random number in the range of `[0, 1)` (including 0.0, excluding 1.0). This explicitly includes traces that aren't sampled, as well as when the `tracesSampleRate` is set to `0.0` or `1.0`.
-2. It is _recommended_ to generate the random number deterministically using the trace ID as seed or source of randomness. The exact method by which the random number is created is implementation defined and may vary between SDK implementations. See 4. on why this behaviour is desirable.
-3. On incoming traces, an SDK assumes the `sample_rand` value along with the rest of the DSC, overriding an existing value if needed.
-4. If `sample_rand` is missing on an incoming trace, the SDK creates and from now on propagates a new random number on-the-fly, based on the following rules:
-   1. If `sample_rate` and the sampling decision (from the `sentry-trace` header) are propgated, create `sample_rand` so that it adheres to the invariant. This means, for a decision of `True` generate a random number in half-open range `[0, rate)` and for a decision of `False` generate a random number in range `[rate, 1]`.
-   2. If the sampling decision is missing, generate a random number in range of `[0, 1)` (including 0.0, excluding 1.0), like for a new trace.
+The SDK should always use the stored random number (`sentry-sample_rand`) for sampling decisions and should not directly rely on `math.random()` when deciding to sample or not:
 
-The SDK should always use the stored random number (`sentry-sample_rand`) for sampling decisions and should no longer rely on `math.random()` or similar functions in tracing code:
+1. When the `tracesSampler` is invoked, the return value should be compared with `sample_rand`: `trace["sentry-sample_rand"] < tracesSampler(context)`
+1. When there is an incoming trace, the SDK fully inherits incoming sampling decisions from the `sentry-trace` header.
+1. Otherwise, when the SDK is the head of a trace (and `tracesSampleRate` is defined), the sampling is done comparing the `tracesSampleRate` with the `sample_rand`: `trace["sentry-sample_rand"] < config.tracesSampleRate`
 
-1. When the `tracesSampler` is invoked, this also applies to the return value of traces sampler. That is, `trace["sentry-sample_rand"] < tracesSampler(context)`
-2. Otherwise, when the SDK is the head of a trace, this also applies to sample decisions based on `tracesSampleRate`. That is, `trace["sentry-sample_rand"] < config.tracesSampleRate`
-3. There is no more direct comparison with `math.random()` during the sampling process.
-
-When using a `tracesSampler`, the proper way to inherit a parent's sampling decision is to return the parent's sample rate, instead of leaving the decision as a float (for example, 1.0). This way, Sentry can still extrapolate counts correctly.
+Something that should be documented for every SDK is the recommended way to use a `tracesSampler` to inherit the parent's sampling decision using the `parentSampleRate`. This way, Sentry can still extrapolate counts correctly:
 
 ```js
 tracesSampler: ({ name, parentSampleRate }) => {

develop-docs/self-hosted/geolocation.mdx

@@ -24,7 +24,11 @@ With this configuration file in place, subsequent runs of Sentry's `install.sh`
 
 1. For the `web` service: **User Settings > Security > Session History** should display country code and region (for example, "US (CA)") underneath the IP addresses in the table.
 
-It's normal to see the `sentry_self_hosted_geoipupdate_1` container exit soon after startup, since updating the geolocation database is a one-off batch process and not a long-running job.
+If you ever need to manually refresh the IP address geolocation database, you can run the following command:
+
+```bash
+./install/geoip.sh
+```
 
 ## Upgrading
 

develop-docs/self-hosted/index.mdx

@@ -25,7 +25,7 @@ To put things simply, consider self-hosted as the Business plan without any soft
 
 ## Getting Started
 
-Our recommendation is to download the [latest release of the self-hosted repository](https://github.com/getsentry/self-hosted/releases/latest), and then run `./install.sh` inside this directory. This script will take care of all the things you need to get started, including a base-line configuration, and then will tell you to run `docker compose up -d` to start Sentry. Sentry binds to port `9000` by default. You should be able to reach the login page at [http://127.0.0.1:9000](http://127.0.0.1:9000/).
+Our recommendation is to download the [latest release of the self-hosted repository](https://github.com/getsentry/self-hosted/releases/latest), and then run `./install.sh` inside this directory. This script will take care of all the things you need to get started, including a base-line configuration, and then will tell you to run `docker compose up --wait` to start Sentry. Sentry binds to port `9000` by default. You should be able to reach the login page at [http://127.0.0.1:9000](http://127.0.0.1:9000/).
 
 To have easy maintainability for future upgrades, it is recommended to use Git workflow by cloning the self-hosted repository and check out to a specific CalVer tag. More about this on [Releases & Upgrading](/self-hosted/releases/).
 
@@ -142,7 +142,7 @@ You very likely will want to adjust the default configuration for your Sentry in
 
 1. **`sentry/enhance-image.sh`**—To install plugins and their dependencies or make other modifications to the Sentry base image, copy `sentry/enhance-image.example.sh` to `sentry/enhance-image.sh` and add necessary steps there. For example, you can use `apt-get` to install dependencies and use `pip` to install plugins. After making modifications to `sentry/enhance-image.sh`, run `./install.sh` again to apply them.
 
-1. **Environment variables**—The available keys are defined in [.env](https://github.com/getsentry/self-hosted/blob/master/.env). Use some system-dependent means of setting environment variables if you need to override any of them. To avoid Git changes, simply create a file called `.env.custom` and insert your system-dependent environment variables there. In order to use this, please use `docker compose --env-file /path/to/.env.custom up -d`.
+1. **Environment variables**—The available keys are defined in [.env](https://github.com/getsentry/self-hosted/blob/master/.env). Use some system-dependent means of setting environment variables if you need to override any of them. To avoid Git changes, simply create a file called `.env.custom` and insert your system-dependent environment variables there. In order to use this, please use `docker compose --env-file /path/to/.env.custom up --wait`.
 
 1. [Geolocation](/self-hosted/geolocation/) uses **a custom configuration file** to conform to the underlying technology.
 
@@ -183,11 +183,11 @@ Please keep in mind to check the `.env` file for changes, when you perform an up
 For all Docker Compose commands, you should specify your `.env.custom`, otherwise the default `.env` file will be used. Some examples are:
 
 ```bash
-docker compose --env-file .env.custom up -d
+docker compose --env-file .env.custom up --wait
 
 # You can also specify the original `.env` file as a fallback if the
 # environment variable doesn't exists on the `.env.custom` file.
-docker compose --env-file .env --env-file .env.custom up -d
+docker compose --env-file .env --env-file .env.custom up --wait
 ```
 
 ### Enhance Sentry image

develop-docs/self-hosted/releases.mdx

@@ -38,7 +38,7 @@ We may have some updated configuration, especially for new features, so always c
 
 If you have a `.env.custom` file, make sure to copy new environment variables from the `.env` file into the `.env.custom` file before running the install script.
 
-Finally, to upgrade, run `./install.sh`. Upon completion, run `docker compose up -d` (or if you have `.env.custom` file, run `docker compose --env-file .env --env-file .env.custom up -d`).
+Finally, to upgrade, run `./install.sh`. Upon completion, run `docker compose up --wait` (or if you have `.env.custom` file, run `docker compose --env-file .env --env-file .env.custom up --wait`).
 
 ### Hard Stops
 

develop-docs/self-hosted/troubleshooting/kafka.mdx

@@ -76,7 +76,7 @@ The _nuclear option_ is removing all Kafka-related volumes and recreating them w
     ```
  4. Start the instance:
     ```shell
-    docker compose up -d
+    docker compose up --wait
     ```
 ## Reducing disk usage
 

docs/contributing/approach/index.mdx

@@ -33,7 +33,7 @@ If you're uncertain, [ask](https://github.com/getsentry/sentry-docs/issues).
 Keep these concepts in mind when contributing to docs:
 
 1. Technical accuracy is our primary consideration. Our content helps every developer diagnose, fix, and optimize their code.
-2. Use inclusive language, which we discuss more fully [here](https://develop.sentry.dev/inclusion/).
+2. Use inclusive language, which we discuss more fully [here](https://develop.sentry.dev/getting-started/inclusive-language/).
 3. Feedback is a gift - share your PR so we can improve our content.
 
 <PageGrid />

docs/platforms/flutter/enriching-events/viewhierarchy/index.mdx

@@ -21,6 +21,31 @@ View hierarchy debugging is an opt-in feature. You can enable it as shown below:
 
 <PlatformContent includePath="enriching-events/attach-viewhierarchy" />
 
+### Customize View Hierarchy Capturing
+
+<Note>
+
+Requires SDK version `8.13.0` or higher.
+
+</Note>
+
+Capturing view hierarchies on Flutter is limited to once every 2 seconds by default to minimize performance impact. While this debounce interval is fixed, you can override individual capture decisions by implementing the `beforeCaptureViewHierarchy` option in your `SentryFlutterOptions`.
+
+The `beforeCaptureViewHierarchy` option allows you to customize behavior based on event data so you can decide when to capture view hierarchy and when not to. For example, you can decide to only capture view hierarchy for fatal events:
+
+```flutter {2-9}
+await SentryFlutter.init((options) {
+  options.beforeCaptureViewHierarchy = (event, hint, debounce) async {
+    // If debounce is active, skip capturing
+    if (debounce) {
+      return false;
+    }
+    // Capture if it's a fatal event
+    return event.level == SentryLevel.fatal;
+  };
+});
+```
+
 ## Viewing View Hierarchy Attachments
 
 View hierarchies appear in the "Attachments" tab, where you can view all attachments, as well as associated events. Click the event ID to open the [Issue Details](/product/issues/issue-details) page of that specific event.

docs/platforms/javascript/common/configuration/integrations/prisma.mdx

@@ -24,7 +24,7 @@ supported:
 
 <Alert level="info">
 
-This integration only works in the Node.js and Bun runtimes.
+This integration only works in the Node.js and Bun runtimes. This integration only supports Prisma v5 at the current time. If you're interested in Prisma v6 support, please leave your thoughts on the [Prisma v6 tracking issue for the Sentry SDK](https://github.com/getsentry/sentry-javascript/issues/14793).
 
 </Alert>
 
@@ -51,3 +51,8 @@ Sentry.init({
   integrations: [Sentry.prismaIntegration()],
 });
 ```
+
+
+## Supported Versions
+
+- `prisma`: `>=5 <6`