Merge master to get AI Code Review changes from PR #14991

Author: Shannon Anahata

develop-docs/development-infrastructure/environment/index.mdx

@@ -102,13 +102,17 @@ Just like running `sentry` (see above), you can start the `devservices` using th
 devservices up
 ```
 
-You will also need to enable workers which you can do so by running the following command:
+To run tasks, you will also need to start taskbroker:
 
 ```shell
-devservices up taskbroker
+# start just taskbroker
+devservices up --mode=taskbroker
+
+# start taskbroker and a backgrond worker
+devservices up --mode=taskworker
 ```
 
-or use a --mode that includes workers. If you use the --mode flag of devservices, any modes that started celery workers will now start taskbroker and a taskworker.
+If you use the `--mode` flag of devservices, any modes that started celery workers will now start taskbroker and a taskworker.
 
 After that, you can start the development server inside the `getsentry` folder:
 

develop-docs/development-infrastructure/ngrok.mdx

@@ -102,7 +102,7 @@ In two separate terminal windows, start the devserver for the control and region
 
 First, start the taskbroker:
 ```shell
-devservices up taskbroker
+devservices up --mode=taskbroker
 ```
 
 ```shell

develop-docs/ingestion/relay/relay-best-practices.mdx

@@ -16,6 +16,18 @@ Make sure changes to the event protocol and APIs are forward-compatible. Relay s
 or truncate data it does not understand. It is a supported use-case to have customers running
 outdated Relays but up-to-date SDKs.
 
+For example, `enum`s in the event protocol (or any other data type received from the SDK) need to have a catchall variant
+such that customer relays running an older version can still forward the data:
+
+```rust
+enum EventColor {
+    Red,
+    Green,
+    Blue,
+    /// Unknown color, for forward compatibility.
+    Unknown(String),
+}
+```
 
 ## Feature Gate new Functionality
 

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

@@ -51,89 +51,156 @@ created this exception.
 `stacktrace`
 
 : An optional stack trace object corresponding to the [Stack Trace Interface](/sdk/data-model/event-payloads/stacktrace/).
-
 ## Exception Mechanism
 
-The exception mechanism is an optional field residing in the _Exception
-Interface_. It carries additional information about the way the exception was
-created on the target system. This includes general exception values obtained
-from the operating system or runtime APIs, as well as mechanism-specific values.
+The exception mechanism is an optional field residing in the _Exception Interface_. 
+It carries additional information about the way the exception was created and captured ("capturing mechanism") on the target system. 
+This includes general exception values obtained from the operating system or runtime APIs, as well as capturing mechanism-specific values.
 
 ### Attributes
 
-`type`
+#### `type`
+
+Required (`string`)
+
+The identifier of the capturing mechanism that captured the exception. 
+The chosen mechanism `type` MUST help users as well as Sentry employees determine the responsible mechanism for capturing the exception. 
+This is either instrumentation within our SDKs or users manually capturing exceptions (for example via `captureException`). 
+
+The `type` MUST be _reasonably unique_  to make it possible to identify the integration or SDK API that performed the capture.
+There's no strict uniqueness requirement as in certain situations, multiple paths exist within one instrumentation, in which case it is fine to use a common mechanism `type`.
+
+For user-invoked exception captures (e.g. via `captureException`), the `type` MUST be set to `'generic'`.
+
+For SDK-invoked exception captures, the mechanism `type` value MUST NOT be set to `'generic'` and SHOULD follow the [Trace Origin](/sdk/performance/trace-origin/) naming scheme whenever applicable. 
+For example, if a span is wrapping the exception capture logic, `type` should be equal to this span's `sentry.origin` attribute.
+If no (specific) span is present, the `type` SHOULD be set to an adequate value, following the Trace Origin naming scheme as closely as possible. 
+
+<Expandable title="Examples">
 
-: Required unique identifier of this mechanism determining rendering and processing of the mechanism data.
+Exception capture within a span:
 
-`description`
+```js
+startSpan(
+  {
+    name: 'Middleware',
+    attributes: { 'sentry.origin': 'auto.http.express.middleware' },
+  },
+  () => {
+    captureException(error, { 
+      mechanism: { type: 'auto.http.express.middleware', handled: false } 
+    });
+  },
+);
+```
+
+Exception capture outside of a span:
+
+```js
+captureException(error, { 
+  mechanism: { type: 'auto.browser.global_handlers.onerror', handled: false } 
+});
+```
+
+Use `'generic'` for user-invoked exception captures (i.e. default value):
+
+```js
+function captureException(error, context) {
+  const mechanism = {
+    type: 'generic',
+    handled: true,
+    ...context?.mechanism,
+  } 
+  // ...
+}
+```
 
-: Optional human-readable description of the error mechanism and a possible hint on how to solve this error.
 
-`help_link`
+</Expandable>
 
-: Optional fully qualified URL to an online help resource, possibly interpolated with error parameters.
+<Expandable title="Why Trace Origin?">
 
-`handled`
+Historically, there was no requirement for the `type` attribute naming scheme. 
+Consequently, different SDKs took diffferent approaches as to how they set the `type` attribute. 
+In some cases, the `type` attribute was/is not set at all. 
+Chosing [Trace Origin](/sdk/performance/trace-origin/) as the naming scheme for the `type` attribute means that we're using an already established and accepted naming scheme.
+The scheme works well enough for the exception mechanism `type` attribute. 
+Slight deviations to accomodate for the applicability to exceptions are allowed and to be expected.
+SDK maintainers are free to migrate to the new naming scheme for existing capturing mechanisms or use it when adding new mechanisms.
 
-: Optional flag indicating whether the user has handled the exception (for example, via `try ... catch`).
+</Expandable>
 
-`synthetic`
+#### `handled`
 
-: An optional flag indicating that this error is synthetic. Synthetic errors are errors that
-carry little meaning by themselves. This may be because they are created at a central
-place (like a crash handler), and are all called the same: `Error`, `Segfault` etc.
-When the flag is set, Sentry will then try to use other information (top in-app frame
-function) rather than the exception type and value in the UI for the primary event display.
-Furthermore, if this flag is set, Sentry will ignore the exception `type` when grouping the
-exception into issues.
-: This flag should be set for all "segfaults" for instance as every single error group would
-look very similar otherwise. Also, errors the SDK creates to add a stack trace to events
-that don't have one themselves should be marked as `synthetic` (This happens, for example, 
-when users set `attachStackTrace: true` and capture a string message via `captureException` 
-or `captureMessage`.)
+Optional (`boolean`)
 
-`exception_id`
+Flag indicating whether the user has handled the exception (for example, via `try ... catch`).
 
-: An optional numeric value providing an ID for the exception relative
-to this specific event. The SDK should assign simple incrementing integers
-to each exception in the tree, starting with 0 for the root of the tree.
-In other words, when flattened into the list provided in the exception
-values on the event, the last exception in the list should have ID 0,
-the previous one should have ID 1, the next previous should have ID 2, etc.
+#### `description`
 
-`parent_id`
+Optional (`string`) 
 
-: An optional numeric value pointing at the exception_id that is the
-parent of this exception. The SDK should assign this to all exceptions except
-the root exception (the last to be listed in the exception values).
+Human-readable description of the error mechanism and a possible hint on how to solve this error.
 
-`is_exception_group`
+#### `help_link`
 
-: An optional flag indicating that this exception is part of an exception group type specific to the platform or language.
+Optional (`string`)
 
-`source`
+Fully qualified URL to an online help resource, possibly interpolated with error parameters.
 
-: 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.
+#### `synthetic`
+
+Optional (`boolean`)
+
+Flag indicating that this error is synthetic. 
+Synthetic errors are errors that carry little meaning by themselves. 
+This may be because they are all created at a central place (like a crash handler), and share the same title: `Error`, `Segfault` etc.
+When the flag is set, Sentry will then try to use other information (top in-app frame function) rather than the exception type and value in the UI for the primary event display.
+Furthermore, if this flag is set, Sentry will ignore the exception `type` when grouping the exception into issues.
+This flag SHOULD be set for all "segfaults" for instance as every single error group would look very similar otherwise. 
+Also, errors the SDK creates to add a stack trace to events that don't have one themselves SHOULD be marked as `synthetic` (This happens, for example, when users set `attachStackTrace: true` and capture a string message via `captureException` or `captureMessage`.)
+
+#### `exception_id`
+
+Optional (`number`)
+
+An optional numeric value providing an ID for the exception relative to this specific event. 
+The SDK SHOULD assign simple incrementing integers to each exception in the tree, starting with 0 for the root of the tree.
+In other words, when flattened into the list provided in the exception values on the event, the last exception in the list SHOULD have ID 0,
+the previous one SHOULD have ID 1, the next previous SHOULD have ID 2, etc.
+
+#### `parent_id`
+
+Optional (`number`)
+
+An optional numeric value pointing at the exception_id that is the parent of this exception. 
+The SDK SHOULD assign this to all exceptions except the root exception (the last to be listed in the exception values).
+
+#### `is_exception_group`
+
+Optional (`boolean`)
+
+Flag indicating that this exception is part of an exception group type specific to the platform or language.
+
+#### `source`
+
+Optional (`string`)
+
+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
-mechanism (see [meta information](#meta-information)).
+#### `meta`
 
-`data`
+Optional information from the operating system or runtime on the exception mechanism (see [meta information](#meta-information)).
 
-: Arbitrary extra data that might help the user understand the error thrown by
-this mechanism.
+#### `data`
 
-<Alert title="Note" level="warning">
-The <code>type</code> attribute is required to send any exception mechanism attribute, even
-if the SDK cannot determine the specific mechanism. In this case, set the <code>type</code>
-to <code>generic</code>. See below for an example.
-</Alert>
+Arbitrary extra data that might help the user understand the error thrown by this mechanism.
 
 ### Meta information
 

develop-docs/sdk/expected-features/index.mdx

@@ -233,7 +233,7 @@ Whenever possible, avoid adding the attachment altogether if taking the screensh
 
 ## Before-Send Hook
 
-Hook called with the event (and on some platforms the hint) that allows the user to decide whether an event should be sent or not.  This can also be used to further modify the event. This only works for `error` events. For `transactions` it is recommended to have `beforeSendTransaction` implemented in SDKs. To understand when you should call this in your SDK, please refer to the [error filter ordering of sessions](/sdk/telemetry/sessions/#filter-order).
+Hook called with the event (and on some platforms the hint) that allows the user to decide whether an event should be sent or not.  This can also be used to further modify the event. This only works for `error` events. Other event types like `transactions` and `check-ins` **should not** go through `beforeSend`. For `transactions` it is recommended to have `beforeSendTransaction` implemented in SDKs. For `check-ins` you can optionally implement `beforeSendCheckIn`. To understand when you should call this in your SDK, please refer to the [error filter ordering of sessions](/sdk/telemetry/sessions/#filter-order).
 
 ## Before-Breadcrumb Hook
 

develop-docs/sdk/platform-specifics/serverless-sdks/aws-lambda.mdx

@@ -5,9 +5,11 @@ sidebar_order: 10
 
 Lambda functions can be written in numerous programming languages (JavaScript,
 Python, Ruby, Java, Go, ...). Sentry is currently supporting automatic
-instrumentation of Lambda functions written in JavaScript and Python.
+instrumentation of Lambda functions written in [JavaScript](https://docs.sentry.io/platforms/javascript/guides/aws-lambda/)
+and [Python](https://docs.sentry.io/platforms/python/integrations/aws-lambda/).
 
-See the [Sentry Documentation](https://docs.sentry.io/product/integrations/cloud-monitoring/) on how to set up serverless instrumentation.
+See the [Sentry Documentation](https://docs.sentry.io/product/integrations/cloud-monitoring/)
+on how to set up serverless instrumentation.
 
 ## A short primer into AWS Lambda functions, and layers.
 
@@ -79,3 +81,7 @@ this can be found [here](https://github.com/getsentry/sentry-javascript/blob/mas
 
 To deploy a new version of the Lambda layer to AWS, you need to trigger a new
 release of the JavaScript SDK.
+
+### Development Environment
+
+When working on the Sentry AWS Lambda layer, the workflow is that you have your example Lambda function in a dev account on AWS and then deploy your local layer and attach it to your example function. How to do this in Python is described in the [contribution guide](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md#contributing-to-sentry-aws-lambda-layer) of the Python SDK.

develop-docs/sdk/telemetry/check-ins.mdx

@@ -159,3 +159,7 @@ monitors frontend APIs.
 `unit`
 
 : **String, required**. The interval unit. Should be one of `year`, `month`, `week`, `day`, `hour`, `minute`.
+
+## Interaction with `beforeSend`
+
+Check-in events in the SDK should **not** go through `beforeSend`. SDKs can optionally implement a dedicated `beforeSendCheckIn` hook that only applies to check-in events.

docs/cli/logs.mdx

@@ -0,0 +1,94 @@
+---
+title: "Logs"
+sidebar_order: 5
+description: "Learn how to view and stream logs using the Sentry CLI."
+---
+
+The `sentry-cli` tool can be used to view and stream logs from your Sentry projects. This allows you to monitor your application logs directly from the command line.
+
+## Requirements
+
+To use the logs command, you need to:
+
+- [Install](/cli/installation) the Sentry CLI
+- [Authenticate](/cli/configuration) with Sentry using an auth token
+- Have logs enabled for your project
+
+## Configuration
+
+The logs command uses your Sentry auth token for authentication. You can configure this using:
+
+```bash
+sentry-cli login
+```
+
+Or by setting the `SENTRY_AUTH_TOKEN` environment variable:
+
+```bash
+export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
+```
+
+Learn more about the CLI's [configuration file](/cli/configuration#configuration-file).
+
+## Basic Usage
+
+The logs command supports two main operations: listing logs and streaming logs in real-time.
+
+### List Logs
+
+To fetch and display logs:
+
+```bash
+sentry-cli logs list --project=my-project --org=my-org
+```
+
+### Stream Logs
+
+To continuously stream logs in real-time:
+
+```bash
+sentry-cli logs list --project=my-project --org=my-org --live
+```
+
+The live streaming mode will continuously poll for new logs and display them as they arrive.
+
+## Command Options
+
+### Project and Organization
+
+Specify the project and organization explicitly:
+
+```bash
+sentry-cli logs list --project=my-project --org=my-org
+```
+
+Or use the default values from your configuration file.
+
+## Examples
+
+### Monitor Application Logs
+
+Stream logs from your production application:
+
+```bash
+sentry-cli logs list --project=my-app --org=my-org --live
+```
+
+### View Recent Logs
+
+Fetch and display logs from your project:
+
+```bash
+sentry-cli logs list --project=my-app --org=my-org
+```
+
+## Output Format
+
+The logs command displays log entries with the following information:
+
+- Timestamp
+- Log level
+- Message
+- Trace ID (if present)
+
+Log entries are displayed in a readable format, making it easy to monitor your application's logging output directly from the command line.