Merge branch 'master' into kahest/mobile-sdk-overhead-fixes

Author: Karl Heinz Struggl

.github/workflows/lint-404s.yml

@@ -25,7 +25,7 @@ jobs:
               - 'platform-includes/**'
             dev-docs:
               - 'develop-docs/**'
-      - uses: oven-sh/setup-bun@v1
+      - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
 

develop-docs/engineering-practices/rust.mdx

@@ -7,7 +7,7 @@ sidebar_order: 40
 ## Getting Started
 
 - A quick introduction into the Syntax for first-timers:
-  [A half-hour to learn Rust](https://fasterthanli.me/blog/2020/a-half-hour-to-learn-rust/)
+  [A half-hour to learn Rust](https://fasterthanli.me/articles/a-half-hour-to-learn-rust)
 - The Rust Book, comprehensively documenting the language:
   [The Rust Programming Language](https://doc.rust-lang.org/book/)
 - [The Async Book](https://rust-lang.github.io/async-book/)

develop-docs/self-hosted/index.mdx

@@ -178,6 +178,16 @@ By default, there exists no `.env.custom` file. In this case, you can manually a
 
 Please keep in mind to check the `.env` file for changes, when you perform an upgrade of Sentry, so that you can adjust your `.env.custom` accordingly, if required, as `.env` is ignored entirely if `.env.custom` is present.
 
+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
+
+# 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
+```
+
 ### Enhance Sentry image
 
 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.

develop-docs/self-hosted/releases.mdx

@@ -36,8 +36,9 @@ git checkout 23.11.0
 
 We may have some updated configuration, especially for new features, so always check the example config files under the <Link to="https://github.com/getsentry/self-hosted/blob/master/sentry/">sentry directory</Link> and see if you need to update your existing configuration. We do our best to automate critical configuration updates, but you should always check your configs during upgrades.
 
-Finally, to upgrade, just run `./install.sh`.
+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`).
 
 ### Hard Stops
 

docs/concepts/data-management/event-grouping/stack-trace-rules.mdx

@@ -6,9 +6,27 @@ description: "Learn how to use stack trace rules to group incoming events based
 
 <Include name="only-error-issues-note.mdx" />
 
-If you use stack traces for grouping, the stack trace rules (previously known as _grouping enhancements_) influence the data that's fed into the grouping algorithm. These rules can be configured on a per-project basis in **[Project] > Settings > Issue Grouping > Stack Trace Rules**.
+Stack trace rules improve issue tracking by ensuring accurate grouping and better classification of stack frames as in-app or system. This helps focus on relevant code, reduces noise, and minimizes false positives. By tailoring rules to your project, you can streamline debugging and maintain consistency across teams or multiple applications.
 
-Each line is a single rule; one or multiple match expressions are followed by one or multiple actions to be executed when all expressions match. All rules are executed from top to bottom on all frames in the stack trace.
+When you set stack trace rules (previously known as _grouping enhancements_) for grouping in Sentry, they influence the data that's fed into the grouping algorithm. These rules can be configured on a per-project basis by going to your project settings and then clicking on "Issue Grouping". 
+
+Here are a few things to note about stack trace rules:
+
+- Each rule is written on a single line.
+- Rules consist of one or more match expressions followed by one or more actions triggered when all expressions match.
+- Rules are applied sequentially, from top to bottom, across all frames in the stack trace.
+
+In addition, the stack trace rules using the below matchers and actions can also be applied to incoming profiles to improve frame classification (in-app vs system, for example). 
+
+Allowed Matchers:
+  * `stack.abs_path`
+  * `stack.module`
+  * `stack.function`
+  * `stack.package`
+  
+Allowed Actions:
+  * `+app`
+  * `-app`
 
 The syntax for stack trace rules is similar to:
 

docs/platforms/android/data-management/sensitive-data/index.mdx

@@ -54,6 +54,7 @@ Sensitive data may appear in the following areas:
 - User context → Automated behavior is controlled via <PlatformIdentifier name="send-default-pii" />.
 - HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context.
 - Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs.
+- HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed.
 
 For more details and data filtering instructions, see <PlatformLink to="/configuration/filtering/">Filtering Events</PlatformLink>.
 

docs/platforms/apple/common/data-management/sensitive-data/index.mdx

@@ -58,6 +58,7 @@ Sensitive data may appear in the following areas:
 - User context → Automated behavior is controlled via <PlatformIdentifier name="send-default-pii" />.
 - HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context.
 - Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs.
+- HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed.
 
 For more details and data filtering instructions, see <PlatformLink to="/configuration/filtering/">Filtering Events</PlatformLink>.
 

docs/platforms/apple/common/overhead/index.mdx

@@ -0,0 +1,61 @@
+---
+title: SDK Overhead
+description: "Learn about Sentry's Apple SDK overhead and how you can tailor your configuration to minimize it."
+sidebar_order: 7500
+---
+
+Adding new features or dependencies to your app incurs additional costs on resources - CPU time, memory usage, and network bandwidth, among other things. Sentry SDKs are no different. This document adds transparency to the possible overhead that using our SDK can add, and help you find the feature set and configurations that work best for you.
+
+## General Approach
+
+The SDK is designed to have minimal to no impact on user experience. To achieve this, we utilize an array of tools to continuously measure and optimize the performance of our implementations.
+
+We also employ various techniques to ensure we don't add strain on the system's resources along the hot path. On Mobile, this very often means that we offload processing steps, I/O, and other things to a background thread, or we postpone processing to a later time if possible.
+
+If you find (for example via local Profiling, or using Sentry to improve the performance of your app) that the SDK does not operate within the guidelines mentioned below, please [open an issue](https://github.com/getsentry/sentry-cocoa/issues/new/choose) on our SDK repo and make sure you provide as much context as you can.
+
+## Error Monitoring
+
+During regular operation, error monitoring incurs little to no overhead. Once an error or crash occurs, the user experience is compromised, and any crash handling routines operate under time constraints imposed by the system. This means that these implementations are highly optimized to perform the required work as quickly as possible.
+
+The SDK also provides methods to manually capture events: <PlatformLink to="/usage/#capturing-errors">`captureError`</PlatformLink> and <PlatformLink to="/usage/#capturing-messages">`captureMessage`</PlatformLink>. These methods perform some complex operations, such as capturing stack trace information, and while they are highly optimized as well, calling them in tight loops should be avoided.
+
+<PlatformSection supported={["apple.ios", "apple.visionos"]}>
+
+## Screenshots and View Hierarchy
+
+If you activate these features, the SDK will capture <PlatformLink to="/enriching-events/screenshots">Screenshots</PlatformLink> and <PlatformLink to="/enriching-events/viewhierarchy">View Hierarchy</PlatformLink> of the app's UI at the time of an error or crash. This incurs a small overhead that is unnoticeable during normal operation.
+
+If your app raises many errors in a tight loop, it can become too much to process quickly enough, and UI jank can be the result, so make sure you handle such cases appropriately. The SDK provides callbacks to fine-tune when to capture <PlatformLink to="/enriching-events/screenshots#customize-screenshot-capturing">Screenshots</PlatformLink> and <PlatformLink to="/enriching-events/viewhierarchy#customize-view-hierarchy-capturing">View Hierarchy</PlatformLink>, which can also be used to reduce performance impact in scenarios where you don't need screenshots or view hierarchies.
+
+</PlatformSection>
+
+## Breadcrumbs
+
+<PlatformLink to="/enriching-events/breadcrumbs">Breadcrumbs</PlatformLink> are collected through automated integrations or by manually adding them. To have them readily available for every event generated by the SDK, they are continuously persisted, and managed in a performant buffer. This shouldn't impact user experience.
+
+Capturing excessive numbers of breadcrumbs (for example, creating breadcrumbs for all log messages) can cause significant performance overhead. To mitigate this, review and adapt your app's usage of breadcrumbs. For example, increase the min-level of log messages that create breadcrumbs from `warn` to `error`.
+
+Note that increasing the max number of breadcrumbs **does not** improve performance and can even have a detrimental effect.
+
+## Tracing and Performance Monitoring
+
+As stated in our <Link to="/product/performance/performance-overhead">product docs on the topic</Link>, Tracing adds some overhead, but should have minimal impact on the performance of your application. In typical scenarios, the expected overhead is less than 3% of the app's resource utilization.
+
+<PlatformSection supported={["apple.ios", "apple.macos"]}>
+
+## Profiling
+
+As stated in our <Link to="/product/explore/profiling/performance-overhead">product docs on the topic</Link>, Profiling adds some overhead, but should have minimal impact on the performance of your application. In typical scenarios, the expected overhead is less than 5% of the app's resource utilization.
+
+</PlatformSection>
+
+<PlatformSection supported={["apple.ios"]}>
+
+## Session Replay
+
+As stated in our <Link to="/product/explore/session-replay/mobile/performance-overhead">product docs on the topic</Link>, Session Replay adds some overhead, but should have minimal impact on the performance of your application. For more details on the measured overhead, read the <PlatformLink to="/session-replay/performance-overhead/">performance overhead docs for this SDK</PlatformLink>.
+
+Note that this feature is still under development. We're working on performance improvements to mitigate a known issue where active Session Replay recording can currently introduce slow frames, especially on older iOS devices (for example iPhone 8).
+
+</PlatformSection>

docs/platforms/dart/data-management/sensitive-data/index.mdx

@@ -48,6 +48,7 @@ Sensitive data may appear in the following areas:
 - User context → Automated behavior is controlled via <PlatformIdentifier name="send-default-pii" />.
 - HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context.
 - Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs.
+- HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed.
 
 For more details and data filtering instructions, see <PlatformLink to="/configuration/filtering/">Filtering Events</PlatformLink>.
 

docs/platforms/dart/overhead/index.mdx

@@ -0,0 +1,33 @@
+---
+title: SDK Overhead
+description: "Learn about Sentry's Dart SDK overhead and how you can tailor your configuration to minimize it."
+sidebar_order: 7500
+---
+
+Adding new features or dependencies to your app incurs additional costs on resources - CPU time, memory usage, and network bandwidth, among other things. Sentry SDKs are no different. This document adds transparency to the possible overhead that using our SDK can add, and help you find the feature set and configurations that work best for you.
+
+## General Approach
+
+The SDK is designed to have minimal to no impact on user experience. To achieve this, we utilize an array of tools to continuously measure and optimize the performance of our implementations.
+
+We also employ various techniques to ensure we don't add strain on the system's resources along the hot path. On Mobile, this very often means that we offload some tasks to native implementations, use debouncing when appropriate, or we postpone processing to a later time if possible.
+
+If you find (for example via local Profiling, or using Sentry to improve the performance of your app) that the SDK does not operate within the guidelines mentioned below, please [open an issue](https://github.com/getsentry/sentry-dart/issues/new/choose) on our SDK repo and make sure you provide as much context as you can.
+
+## Error Monitoring
+
+During regular operation, error monitoring incurs little to no overhead. Once an error or crash occurs, the user experience is compromised, and any crash handling routines operate under time constraints imposed by the system. This means that these implementations are highly optimized to perform the required work as quickly as possible.
+
+The SDK also provides methods to manually capture events: <PlatformLink to="/usage/#capturing-errors">`captureError`</PlatformLink> and <PlatformLink to="/usage/#capturing-messages">`captureMessage`</PlatformLink>. These methods perform some complex operations, such as capturing stack trace information, and while they are highly optimized as well, calling them in tight loops should be avoided.
+
+## Breadcrumbs
+
+<PlatformLink to="/enriching-events/breadcrumbs">Breadcrumbs</PlatformLink> are collected through automated integrations or by manually adding them. To have them readily available for every event generated by the SDK, they are continuously persisted, and managed in a performant buffer. This shouldn't impact user experience.
+
+Capturing excessive numbers of breadcrumbs (for example, creating breadcrumbs for all log messages) can cause significant performance overhead. To mitigate this, review and adapt your app's usage of breadcrumbs. For example, increase the min-level of log messages that create breadcrumbs from `warn` to `error`.
+
+Note that increasing the max number of breadcrumbs **does not** improve performance and can even have a detrimental effect.
+
+## Tracing and Performance Monitoring
+
+As stated in our <Link to="/product/performance/performance-overhead">product docs on the topic</Link>, Tracing adds some overhead, but should have minimal impact on the performance of your application. In typical scenarios, the expected overhead is less than 3% of the app's resource utilization.