diff --git a/develop-docs/self-hosted/configuration.mdx b/develop-docs/self-hosted/configuration.mdx index 1826c66ca3817..efb014b988127 100644 --- a/develop-docs/self-hosted/configuration.mdx +++ b/develop-docs/self-hosted/configuration.mdx @@ -77,5 +77,5 @@ Here is further information on specific configuration topics related to self-hos - [Email](/self-hosted/email/) - [Geolocation](/self-hosted/geolocation/) - [Single Sign-On (SSO)](/self-hosted/sso/) -- [Content Security Policy](/self-hosted/experimental/csp/) -- [Errors Only](/self-hosted/experimental/errors-only/) +- [Content Security Policy](/self-hosted/optional-features/csp/) +- [Errors Only](/self-hosted/optional-features/errors-only/) diff --git a/develop-docs/self-hosted/experimental/index.mdx b/develop-docs/self-hosted/experimental/index.mdx deleted file mode 100644 index 0889cc986d786..0000000000000 --- a/develop-docs/self-hosted/experimental/index.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -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!** - - diff --git a/develop-docs/self-hosted/experimental/csp.mdx b/develop-docs/self-hosted/optional-features/csp.mdx similarity index 95% rename from develop-docs/self-hosted/experimental/csp.mdx rename to develop-docs/self-hosted/optional-features/csp.mdx index 7243621d77fb7..fdc872a94bf03 100644 --- a/develop-docs/self-hosted/experimental/csp.mdx +++ b/develop-docs/self-hosted/optional-features/csp.mdx @@ -5,7 +5,7 @@ sidebar_order: 70 --- - This is an experimental feature. This means that features and workflows are not completely tested, so use at your own risk! + This is an experimental feature. This means that features and workflows are not completely tested, use at your own risk! 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`: diff --git a/develop-docs/self-hosted/experimental/errors-only.mdx b/develop-docs/self-hosted/optional-features/errors-only.mdx similarity index 96% rename from develop-docs/self-hosted/experimental/errors-only.mdx rename to develop-docs/self-hosted/optional-features/errors-only.mdx index 20c6dafdfc097..2ebc2d5cebfcb 100644 --- a/develop-docs/self-hosted/experimental/errors-only.mdx +++ b/develop-docs/self-hosted/optional-features/errors-only.mdx @@ -5,7 +5,7 @@ sidebar_order: 100 --- - This is an experimental feature. This means that features and workflows are not completely tested, so use at your own risk! + This is an experimental feature. This means that features and workflows are not completely tested, use at your own risk! Starting from 24.8.0+, users will have the ability to choose between two distinct types of self-hosted Sentry deployments. @@ -34,4 +34,4 @@ This is our default version of self-hosted Sentry. It includes most of the featu 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`. \ No newline at end of file +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`. diff --git a/develop-docs/self-hosted/experimental/external-storage.mdx b/develop-docs/self-hosted/production-enhancements/external-storage.mdx similarity index 95% rename from develop-docs/self-hosted/experimental/external-storage.mdx rename to develop-docs/self-hosted/production-enhancements/external-storage.mdx index 5cb66fe022233..e836173460915 100644 --- a/develop-docs/self-hosted/experimental/external-storage.mdx +++ b/develop-docs/self-hosted/production-enhancements/external-storage.mdx @@ -1,13 +1,9 @@ --- -title: Self Hosted External Storage +title: Self-Hosted External Storage sidebar_title: External Storage -sidebar_order: 90 +sidebar_order: 3 --- - - These are community-contributed docs. Sentry does not officially provide support for self-hosted configurations beyond the default install. - - 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). diff --git a/develop-docs/self-hosted/experimental/monitoring.mdx b/develop-docs/self-hosted/production-enhancements/monitoring.mdx similarity index 76% rename from develop-docs/self-hosted/experimental/monitoring.mdx rename to develop-docs/self-hosted/production-enhancements/monitoring.mdx index aa23462a57809..ce2ff285f995d 100644 --- a/develop-docs/self-hosted/experimental/monitoring.mdx +++ b/develop-docs/self-hosted/production-enhancements/monitoring.mdx @@ -1,14 +1,10 @@ --- title: Self-Hosted Monitoring sidebar_title: Monitoring -sidebar_order: 10 +sidebar_order: 2 --- - - These are community-contributed docs. Sentry does not officially provide support for self-hosted configurations beyond the default install. - - -This page is considered experimental because everyone will have different setup and requirements for their monitoring system. It is also best to use your existing monitoring system, and try to integrate Sentry with it, instead of spinning up a new one. +Everyone will have different setup and requirements for their monitoring system, it is best to use your existing monitoring system, and try to integrate Sentry with it, instead of spinning up a new one. Most containers have a `statsd` client that you can point to your monitoring system. If you have a native `statsd` server instance, you can directly use it. If you don't, you might want to add some kind of converter that converts the ingested `statsd` format into your own. For example, if you are using Prometheus, you can use [prometheus-statsd-exporter](https://github.com/prometheus/statsd_exporter) to bridge the gap. @@ -19,7 +15,7 @@ We recommend [the original `statsd` server made by Etsy](https://github.com/stat Sentry does not provide any alerts if your host instance is low on resources such as free memory or disk space. You will need to configure this own your own relative to your needs. It is critical for you to monitor the disk space as once it gets full, it will be much harder to recover from there. - After changing configuration files, don't forget to restart the containers with `docker compose restart`. See the configuration section for more information. + After changing configuration files, re-run the ./install.sh script, to rebuild and restart the containers. See the configuration section for more information. ## Sentry-related configurations @@ -88,6 +84,8 @@ metrics: # periodic_secs: 5 ``` +Defined metric keys are specified on [statsd.rs file](https://github.com/getsentry/relay/blob/master/relay-server/src/statsd.rs). + ### Symbolicator You can configure Symbolicator to send metrics to Statsd server by configuring your `symbolicator/config.yml` file: @@ -99,6 +97,32 @@ metrics: prefix: "sentry.symbolicator" # Adjust this to your needs, default is "symbolicator" ``` +### Uptime Checker + +You can configure Uptime Checker to send metrics to Statsd server by configuring your `docker-compose.yml` file: + +```yaml +services: + # Other services + uptime-checker: + # ... + environment: + UPTIME_CHECKER_STATSD_ADDR: "100.100.123.123:8125" # It's recommended to use IP address instead of domain name +``` + +### Taskbroker + +You can configure Taskbroker to send metrics to Statsd server by configuring your `docker-compose.yml` file: + +```yaml +services: + # Other services + taskbroker: + # ... + environment: + TASKBROKER_STATSD_ADDR: "100.100.123.123:8125" # It's recommended to use IP address instead of domain name +``` + ## Sentry dependencies We don't provide configurations for Sentry's dependencies such as PostgreSQL, Kafka, Redis, Memcached and ClickHouse that are bundled with the Docker Compose file. You will need to provide monitoring configuration for those service yourself adjusted to your needs. diff --git a/develop-docs/self-hosted/experimental/reverse-proxy.mdx b/develop-docs/self-hosted/production-enhancements/reverse-proxy.mdx similarity index 85% rename from develop-docs/self-hosted/experimental/reverse-proxy.mdx rename to develop-docs/self-hosted/production-enhancements/reverse-proxy.mdx index c60dc962f9091..e91cffbeb52f1 100644 --- a/develop-docs/self-hosted/experimental/reverse-proxy.mdx +++ b/develop-docs/self-hosted/production-enhancements/reverse-proxy.mdx @@ -1,13 +1,9 @@ --- title: Self-Hosted Reverse Proxy sidebar_title: Reverse Proxy -sidebar_order: 80 +sidebar_order: 1 --- - - These are community-contributed docs. Sentry does not officially provide support for self-hosted configurations beyond the default install. - - 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. @@ -22,13 +18,29 @@ We recommend TLS termination to be done on your own dedicated load balancer or p Certain self-hosted deployments requires the dashboard to be accessed only via internal network. But, they also need to provide public Sentry ingestion endpoint for client devices such as mobile and desktop apps. You can expose some of these endpoints publicly: -- `/api/[0-9]+/envelope/` - Main endpoint for submitting event from SDK -- `/api/[0-9]+/minidump/` - Endpoint for submitting minidump from native SDKs -- `/api/[0-9]+/security/` - Endpoint for submitting security-related such as CSP errors -- `/api/[0-9]+/store/` - Old endpoint for submitting event from SDK, it is deprecated. -- `/api/[0-9]+/unreal/` - Endpoint for submitting crash report from Unreal Engine SDK - -The `[0-9]+` is a regular expression string that is acquired from the project DSN. +- `/api/{project_id}/envelope/` - Main endpoint for submitting event from SDK. +- `/api/{project_id}/store/` - Legacy endpoint for submitting event from SDK, it is deprecated. +- `/api/{project_id}/security/` - Endpoint for submitting security-related reports. +- `/api/{project_id}/csp-report/` - Endpoint for submitting [CSP (Content Security Policy) reports](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP). +- `/api/{project_id}/nel/` - Endpoint for submitting [NEL (Network Error Logging)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/NEL) reports. +- `/api/{project_id}/minidump/` and `/api/{project_id}/minidump` - Endpoint for submitting minidump from native SDKs. +- `/api/{project_id}/events/{event_id}/attachments/` - Endpoint for submitting attachments. +- `/api/{project_id}/unreal/{sentry_key}` - Endpoint for submitting crash report from Unreal Engine SDK. +- `/api/{project_id}/cron` - Endpoint for submitting cron monitors from APIs. For more specific endpoints: + - `/api/{project_id}/cron/{monitor_slug}/{sentry_key}/` + - `/api/{project_id}/cron/{monitor_slug}/{sentry_key}` + - `/api/{project_id}/cron/{monitor_slug}/` + - `/api/{project_id}/cron/{monitor_slug}` +- `/api/{project_id}/integration/otlp` - Endpoint for submitting native OTLP dataset (traces, logs and metrics). For more specific endpoints: + - `/api/{project_id}/integration/otlp/v1/traces` - Endpoint for submitting native OTLP dataset (traces). + - `/api/{project_id}/integration/otlp/v1/traces/` - Endpoint for submitting native OTLP dataset (traces). + - `/api/{project_id}/integration/otlp/v1/logs` - Endpoint for submitting native OTLP dataset (logs). + - `/api/{project_id}/integration/otlp/v1/logs/` - Endpoint for submitting native OTLP dataset (logs). + + +The `{project_id}` placeholder should resolve to `[0-9]+` regular expression. + +The `{event_id}`, `{monitor_slug}` and `{sentry_key}` placeholders should resolve to `[A-Za-z0-9-_+=]+` regular expression. ## Rate Limiting @@ -42,6 +54,10 @@ Endpoint for health checks is available on `/_health/` endpoint using HTTP proto ## Reverse Proxy Examples + + If you run your reverse proxy as a Docker container, and place it on the same Docker Compose network as your Sentry instance, make sure to target `nginx:80` instead of `web:9000` in the examples below. + + ### NGINX We recommend installing NGINX since that's what we are using on [sentry.io](https://sentry.io/). diff --git a/develop-docs/self-hosted/reference-architecture/index.mdx b/develop-docs/self-hosted/reference-architecture/index.mdx index 04de3e055a5a2..aaa22dfe48495 100644 --- a/develop-docs/self-hosted/reference-architecture/index.mdx +++ b/develop-docs/self-hosted/reference-architecture/index.mdx @@ -6,5 +6,5 @@ sidebar_order: 3 This section contains reference architectures for self-hosted Sentry other than the default single-node setup. These are not meant to be used as-is, but as a reference for how to deploy self-hosted Sentry around your existing infrastructure. This section can be used to create a scaling strategy if you have higher traffic loads over time. -Please note that these reference architectures do not take external data storage dependencies into account such as Kafka, Postgres, Redis, S3, etc. If you wish to do so, refer to the [Experimental Configurations](/self-hosted/experimental/) section +Please note that these reference architectures do not take external data storage dependencies into account such as Kafka, Postgres, Redis, S3, etc. If you wish to do so, refer to the [Production Enhancements](/self-hosted/production-enhancements/) or [Optional Features](/self-hosted/optional-features/) sections. diff --git a/develop-docs/self-hosted/reference-architecture/separate-ingest-box.mdx b/develop-docs/self-hosted/reference-architecture/separate-ingest-box.mdx index 19c5a7fbbb878..b65ad74bcdb03 100644 --- a/develop-docs/self-hosted/reference-architecture/separate-ingest-box.mdx +++ b/develop-docs/self-hosted/reference-architecture/separate-ingest-box.mdx @@ -4,7 +4,7 @@ sidebar_title: Separate Ingest Box sidebar_order: 2 --- -In addition to having a [separate domain](/self-hosted/experimental/reverse-proxy/#expose-only-ingest-endpoint-publicly) for viewing the web UI and ingesting data, you can deploy a dedicated server for data ingestion that relays information to your main server. This setup is recommended for high-traffic installations and environments with multiple data centers. +In addition to having a [separate domain](/self-hosted/production-enhancements/reverse-proxy/#expose-only-ingest-endpoint-publicly) for viewing the web UI and ingesting data, you can deploy a dedicated server for data ingestion that relays information to your main server. This setup is recommended for high-traffic installations and environments with multiple data centers. This architecture helps mitigate DDoS attacks by distributing ingestion across multiple endpoints, while your main Sentry instance with the web UI should be protected on a private network (accessible via VPN). Invalid payloads sent to your Relay instances will be dropped immediately. If your main server becomes unreachable, your Relay will continue attempting to send the data. diff --git a/develop-docs/self-hosted/reference-architecture/simple-single-box.mdx b/develop-docs/self-hosted/reference-architecture/simple-single-box.mdx index a9d70498f8845..b0172cbc3c93e 100644 --- a/develop-docs/self-hosted/reference-architecture/simple-single-box.mdx +++ b/develop-docs/self-hosted/reference-architecture/simple-single-box.mdx @@ -25,4 +25,4 @@ graph TB internet--> Server ``` -For more information regarding configuring your external load balancer, please refer to the [External Load Balancer](/self-hosted/experimental/reverse-proxy/) section. +For more information regarding configuring your external load balancer, please refer to the [External Load Balancer](/self-hosted/production-enhancements/reverse-proxy/) section.