Merge branch 'master' into feat(apple)/redact-docs

Author: brustolin

develop-docs/application/dynamic-sampling/outcomes.mdx

@@ -0,0 +1,28 @@
+---
+title: The “Indexed” Outcome Category
+sidebar_order: 4
+---
+
+Data types which are subject to dynamic sampling are represented in two different outcome data categories: "total" and "indexed". You can think of the "total" category as counting items that are stored in _aggregated_ form, in other words, as metrics. The "indexed" category counts items that are stored individually.
+
+If an item is dropped _before_ metrics extraction & dynamic sampling, it will show up as an outcome in both categories (for example, `"transaction"`  and `"transaction_indexed"`). If an item is dropped _by_ dynamic sampling, it will show up as a "filtered" outcome in the "indexed" category, but it lives on in the form of metrics, for which we emit an "accepted" outcome in the "total" category.
+
+## Illustration
+
+These charts illustrate the flow of data categories for transactions:
+
+For a sampled transaction:
+
+![](https://mermaid.ink/img/pako:eNp1UT1vgzAQ_SvWzYAgJoA9ZGJru4StdVWdwCGWwI4c04Yi_nsNDI2U1l589z58TzdBbRoJHE6d-arPaB15PgpN_KnKJxKGzqK-Yu2U0WF4IEfZ4bjh6_ORUVZv5aixVzWpsL90Srfv_wo-lG7kTTabcKOV1YNp5YyVf6N3DncsoZcLAfTS9qgaH3BaEPGbUwAnk2_Ug_2USyHAzyrRCiCz0LMX4-BMNeoauLODDGC4NOhkqbC12AM_YXf13Qtq4BPcgCcJi2gRs13BaLYvkl0RwAg8zVjEWBonOaVZwWI6B_BtjHeIo32esyyOk5SmdJcleQCyUT7Hy7aVdTkBWDO05_sPX1f5MtX8Azhkjhw)
+
+For a transaction filtered by dynamic sampling:
+
+![](https://mermaid.ink/img/pako:eNp1UcFSgzAQ_ZXMeoVOaCiQHDxxUy_lpnGcDGzbKCSdNGiR4d8N5WBnqskl-_a9t9ndEWrbIAjYtfarPijnyeNWGhJOVT6QOPZOmZOqvbYmju_JFls1LPnL85ZRVi_lYFSna1Kp7thqs3_9V_CmTYNnbBbhQiurG9PKW4d_Z68ctviOtV9oJz-0SBYkBM5-oLjbUSrNfCGCDl2ndBM6H2eF_B2ABEHGANS9-8Q5kBCaQOUkkEmaKYhV7201mBqEdz1G0B8b5bHUau9UB2Kn2lNAj8qAGOEMIkn4ihWUrwvOsk2RrIsIBhBpxlecpzTJGcsKTtkUwbe1wYGuNnnOM0qTlKVsnSV5BNjoMIanZV2XrUXgbL8_XBd8vsjnX00_t7aW9Q)
+
+## Data Types
+
+The following data categories have a corresponding `"*_indexed"` category:
+
+* transactions
+* spans
+* profiles

develop-docs/development/database-migrations/index.mdx

@@ -5,7 +5,7 @@ sidebar_order: 30
 
 Django migrations are how we handle changes to the database in Sentry.
 
-Django migration official docs: [https://docs.djangoproject.com/en/2.2/topics/migrations/](https://docs.djangoproject.com/en/2.2/topics/migrations/) . These will cover most things you need to understand what a migration is doing.
+Django migration official docs: [https://docs.djangoproject.com/en/5.1/topics/migrations/](https://docs.djangoproject.com/en/5.1/topics/migrations/) . These will cover most things you need to understand what a migration is doing.
 
 ## Commands
 

develop-docs/integrations/discord/index.mdx

@@ -32,10 +32,6 @@ discord.bot-token: "<bot token>"
 
 After you update the <code>config.yml</code>, restart your Sentry server to continue the setup process.
 
-<Alert title="Note" level="info">
-    After changing configuration files, re-run the <code>./install.sh</code> script, to rebuild and restart the containers. See the <Link to="/self-hosted/#configuration">configuration section</Link> for more information.
-</Alert>
-
 ## Configure your Discord interactions endpoint
 
 Now that Sentry is running and it knows your Discord credentials, we need to set up a way for Discord to interact with Sentry.

develop-docs/sdk/event-payloads/breadcrumbs.mdx

@@ -91,6 +91,10 @@ Contains a dictionary whose contents depend on the breadcrumb type. Additional p
 
 : This defines the severity level of the breadcrumb. Allowed values are, from highest to lowest: `fatal`, `error`, `warning`, `info`, and `debug`. Levels are used in the UI to emphasize and deemphasize the crumb. The default is `info`.
 
+`origin` (optional)
+
+: A string representing the origin of the breadcrumb. This is typically used to identify the source of the breadcrumb. For example hybrid SDKs can identify native breadcrumbs from JS or Flutter.
+
 `timestamp` (recommended)
 
 : A timestamp representing when the breadcrumb occurred. The format is either a string as defined in [RFC 3339](https://tools.ietf.org/html/rfc3339) or a numeric (integer or float) value representing the number of seconds that have elapsed since the [Unixepoch](https://en.wikipedia.org/wiki/Unix_time).  

develop-docs/sdk/telemetry/traces/modules/llm-monitoring.mdx

@@ -44,7 +44,7 @@ sentry.init(...)
 
 openai = OpenAI()
 
-@ai_track(description="My AI pipeline")
+@ai_track("My AI pipeline")
 def invoke_pipeline():
     result = openai.chat.completions.create(
         model="some-model", messages=[{"role": "system", "content": "hello"}]

develop-docs/self-hosted/csp.mdx renamed to develop-docs/self-hosted/experimental/csp.mdx

@@ -5,7 +5,7 @@ sidebar_order: 70
 ---
 
 <Alert level="warning">
-  This is an experimental feature. Use it with caution.
+  This is an experimental feature. This means that features and workflows are not completely tested, so use at your own risk!
 </Alert>
 
 Starting with Sentry `23.5.0`, it is possible to enable the [CSP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) on self-hosted Sentry installations. The good news is that Sentry itself supports [collecting of CSP reports](https://docs.sentry.io/product/security-policy-reporting/). We recommend creating a separate Sentry project for CSP reports. To enable CSP and reports collection, you'll want to configure the following settings in `sentry.conf.py`:

develop-docs/self-hosted/experimental/errors-only.mdx

@@ -0,0 +1,37 @@
+---
+title: Errors Only Self-hosted
+sidebar_title: Errors Only
+sidebar_order: 100
+---
+
+<Alert level="warning">
+  This is an experimental feature. This means that features and workflows are not completely tested, so use at your own risk!
+</Alert>
+
+Starting from 24.8.0+, users will have the ability to choose between two distinct types of self-hosted Sentry deployments.
+
+**Errors Only**
+
+Errors Only self-hosted offers a small subset of features with an emphasis on minimizing system resources. This lightweight option includes only the following features:
+1. Issues
+2. Alerts
+3. Integrations
+4. Dashboards
+5. Releases
+6. Discover
+
+In order to enable errors only self-hosted, you'll need to update your [.env file](https://github.com/getsentry/self-hosted/blob/master/.env) to include `COMPOSE_PROFILES=errors-only`.
+
+**Feature Complete**
+
+This is our default version of self-hosted Sentry. It includes most of the features that are available on our SaaS product. This includes everything offered in the Errors Only version, plus the following:
+1. [Traces](https://docs.sentry.io/product/explore/traces/)
+2. [Profiles](https://docs.sentry.io/product/explore/profiling/)
+3. [Replays](https://docs.sentry.io/product/explore/session-replay/)
+4. [Insights](https://docs.sentry.io/product/insights/) (Requests, Queries, Assets, etc)
+5. [User Feedback](https://docs.sentry.io/product/user-feedback/)
+6. [Performance](https://docs.sentry.io/product/performance/)
+7. [Crons](https://docs.sentry.io/product/crons/)
+8. [Metrics](https://docs.sentry.io/product/explore/metrics/)
+
+This version of Sentry is enabled by default upon installation. Ensure that your [.env file](https://github.com/getsentry/self-hosted/blob/master/.env) includes `COMPOSE_PROFILES=feature-complete`.

develop-docs/self-hosted/experimental/external-storage.mdx

@@ -0,0 +1,122 @@
+---
+title: Self Hosted External Storage
+sidebar_title: External Storage
+sidebar_order: 90
+---
+
+In some cases, storing Sentry data on-disk is not really something people can do. Sometimes, it's better to offload it into some bucket storage (like AWS S3 or Google Cloud Storage).
+
+<Alert title="Important" level="warning">
+    These are community-contributed docs. Sentry does not officially provide support for self-hosted configurations beyond the default install.
+</Alert>
+<Alert title="Note" level="info">
+    After changing configuration files, re-run the <code>./install.sh</code> script, to rebuild and restart the containers. See the <Link to="/self-hosted/#configuration">configuration section</Link> for more information.
+</Alert>
+
+## Sentry
+
+Sentry has an abstraction called "filestore" that handles storing attachments, sourcemaps (release artifacts), and replays. Filestore configuration for Sentry should be configured on the `sentry/config.yml` file.
+
+**Important:** `sentry cleanup` command won't delete files that is stored on an external storage such as GCS or S3. You will have to configure your own cleanup mechanism by utilizing your storage provider's object retention configuration. This should be set accordingly to the `SENTRY_EVENTS_RETENTION_DAYS`, although you can set it as a different value than what's set on the Docker Compose file.
+
+### Google Cloud Storage backend
+
+The configuration for GCS backend is pointed to `sentry.filestore.gcs.GoogleCloudStorage`. You will need to set `GOOGLE_APPLICATION_CREDENTIALS` environment variable. For more information, refer to the [Google Cloud documentation for setting up authentication](https://cloud.google.com/storage/docs/reference/libraries#setting_up_authentication).
+
+On your `sentry/config.yml` file, you will need to set the following:
+
+```yaml
+filestore.backend: "gcs"
+filestore.options:
+  bucket_name: "..."
+```
+
+If you set up via service account key, you will need to configure your `docker-compose.yml` file with the following:
+
+```yaml
+x-sentry-defaults: &sentry-defaults
+  # ...
+  environment:
+    # The rest of the environment variables
+    GOOGLE_APPLICATION_CREDENTIALS: "/run/secrets/service_account.json"
+  volumes:
+    # The rest of the volumes
+    - "/path/to/service_account.json:/run/secrets/service_account.json:ro"
+```
+
+### S3 backend
+
+<Alert title="Warning" level="warning">
+  Although S3 support is available, it is not thoroughly tested and is not used by Sentry SaaS. Therefore, it is experimental and not officially supported.
+</Alert>
+
+The configuration for S3-compatible backend is pointed to `sentry.filestore.s3.S3Boto3Storage`.
+
+On your `sentry/config.yml` file, you will need to set the following:
+
+```yaml
+filestore.backend: 's3'
+filestore.options:
+  bucket_acl: 'private'
+  default_acl: 'private'
+  access_key: '<REDACTED>'
+  secret_key: '<REDACTED>'
+  bucket_name: 'my-bucket'
+  region_name: 'auto'
+  endpoint_url: 'https://<REDACTED>' # If you're not using AWS.
+  addressing_style: 'path' # For regular AWS S3, use "auto" or "virtual". For other S3-compatible API like MinIO or Ceph, use "path".
+  signature_version: 's3v4'
+```
+
+Refer to [botocore configuration](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html) for valid configuration values.
+
+## Vroom
+
+Vroom is the service that handles profiling. By default the data for profiling is saved on the local filesystem. On self-hosted deployments, this should be done by overriding the `SENTRY_BUCKET_PROFILES` environment variable. It's also possible that additional environment variables should be added, depending on the backend of choice.
+
+**Important:** `sentry cleanup` command won't delete files that is stored on an external storage such as GCS or S3. You will have to configure your own cleanup mechanism by utilizing your storage provider's object retention configuration. This should be set accordingly to the `SENTRY_EVENTS_RETENTION_DAYS`, although you can set it as a different value than what's set on the Docker Compose file.
+
+### Google Cloud Storage backend
+
+You will need to set `GOOGLE_APPLICATION_CREDENTIALS` environment variable. For more information, refer to the [Google Cloud documentation for setting up authentication](https://cloud.google.com/storage/docs/reference/libraries#setting_up_authentication).
+
+On your `docker-compose.yml` file, you will need to add the following (this assumes you are setting up via service account file):
+
+```yaml
+services:
+  vroom:
+    environment:
+      # The rest of the environment variables
+      SENTRY_BUCKET_PROFILES: "gs://my-bucket"
+      GOOGLE_APPLICATION_CREDENTIALS: "/run/secrets/service_account.json"
+    volumes:
+      # The rest of the volumes
+      - "/path/to/service_account.json:/run/secrets/service_account.json:ro"
+```
+
+### S3 backend
+
+<Alert title="Warning" level="warning">
+  Although S3 support is available, it is not thoroughly tested and is not used by Sentry SaaS. Therefore, it is experimental and not officially supported.
+</Alert>
+
+On your `docker-compose.yml` file, you will need to add the following:
+
+```yaml
+services:
+  vroom:
+    environment:
+      # The rest of the environment variables
+      SENTRY_BUCKET_PROFILES: "s3://my-bucket?awssdk=v1&region=us-west-1&endpoint=amazonaws.com"
+      # For other S3-compatible APIs
+      SENTRY_BUCKET_PROFILES: "s3://my-bucket?awssdk=v1&region=any-region&endpoint=minio.yourcompany.com&s3ForcePathStyle=true&disableSSL"
+      AWS_ACCESS_KEY: "foobar"
+      AWS_SECRET_KEY: "foobar"
+      AWS_SESSION_TOKEN: "foobar" # (optional)
+```
+
+Further explanation on the query string options:
+- `region`: The AWS region for requests.
+- `endpoint`: The endpoint URL (hostname only or fully qualified URI).
+- `disableSSL`: A value of "true" disables SSL when sending requests.
+- `s3ForcePathStyle`: A value of "true" forces the request to use path-style addressing.

develop-docs/self-hosted/experimental/index.mdx

@@ -0,0 +1,7 @@
+---
+title: Experimental Configurations
+---
+
+These pages here are purely experimental and are not officially supported workflows. Much of this is contributed by our wonderful developer community. We hope it is useful for those customizing self-hosted Sentry to your specific needs, but are unable to offer official support or triage for issues arising from these workflows. **Use at your own risk!**
+
+<PageGrid />

develop-docs/self-hosted/reverse-proxy.mdx renamed to develop-docs/self-hosted/experimental/reverse-proxy.mdx

@@ -4,6 +4,10 @@ sidebar_title: Reverse Proxy
 sidebar_order: 80
 ---
 
+<Alert title="Important" level="warning">
+    These are community-contributed docs. Sentry does not officially provide support for self-hosted configurations beyond the default install.
+</Alert>
+
 Adding a reverse proxy in front of your Sentry deployment is strongly recommended for one big reason: you can fine tune every configuration to fit your current setup. A dedicated reverse proxy that does SSL/TLS termination that also forwards the client IP address as Docker Compose internal network (as this is [close to impossible to get otherwise](https://github.com/getsentry/self-hosted/issues/554)) would give you the best Sentry experience.
 
 Once you have setup a reverse proxy to your Sentry instance, you should modify the `system.url-prefix` in the `config.yml` file to match your new URL and protocol. You should also update the SSL/TLS section in the `sentry/sentry.conf.py` script, otherwise you may get CSRF-related errors when performing certain actions such as configuring integrations.