# Operating Guidelines

## Learn about our guidelines for operation when self-hosting external Relays.

This page reviews our guidelines for operation when self-hosting external Relays, that is, Relays that run on your hardware and forward events to `sentry.io`.

## [General Considerations](#general-considerations)

* We recommend [running Relay](/product/relay/getting-started/) using the officially provided Docker image (`getsentry/relay`) found on [DockerHub](https://hub.docker.com/r/getsentry/relay/) and tagged with its Git revision identifier, rather than building from source.

* We recommend running at least two Relay instances (containers) with a reverse proxy (such as [HAProxy](https://www.haproxy.org/) or [Nginx](https://nginx.org)) in front of them for improved availability, simplified Relay updates, and SSL/TLS support.

* To monitor your Relay setup, configure [Logging](/product/relay/monitoring/#logging), [Metrics](/product/relay/monitoring/#metrics), and [Health Checks](/product/relay/monitoring/#health-checks).

## [System Requirements and Recommendations](#system-requirements-and-recommendations)

The following recommendations assume that Relay is run in Docker.

| Resource | Recommendations                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CPU      | - **Required**: x86-64 (amd64) or AArch64 (arm64) CPU architecture - Multi-core CPU [\[1\]](#multi-core-cpu)                                                                                                                                                                                                                                                                                                                                     |
| Memory   | - At least 2GB of RAM per Relay container is recommended.                                                                                                                                                                                                                                                                                                                                                                                        |
| Network  | - Bandwidth: Make sure you have enough capacity to receive and forward the planned data volume. Relay compresses all upstream requests to `sentry.io` by default, but the compression rate might vary depending on the types and shapes of the submitted events. - Latency: Relay can tolerate network delays up to a certain point. It is however recommended to make sure that the round-trip time to the upstream stays lower than 5 seconds. |
| Storage  | - Disk storage is only required if [Spooling](/product/relay/options/#spooling) is configured. See the `spool.envelopes.max_memory_size` configuration option. Otherwise, Relay does not require disk storage.                                                                                                                                                                                                                                   |

[\[1\]](#multi-core-footnote) Relay is a multi-threaded application that tries to leverage all available CPU cores. As a result, Sentry highly recommends running Relay on multi-core CPUs. If your setup is expected to handle more than 100 requests per second, we recommend running Relay on at least four (4) CPU cores. By default, every Relay instance will use the total number of available cores to adjust the sizes of its thread pools. Adjust this behavior by configuring the `limits.max_thread_count`.

## [Relay Binary](#relay-binary)

Every release of Relay also provides a set of binaries that are built for the Operating Systems listed below.

| Operating System | Version                   |
| ---------------- | ------------------------- |
| Ubuntu x64       | 20.04                     |
| Ubuntu ARM       | 22.04                     |
| macOS            | macOS Sonoma (version 14) |
| Windows          | Windows Server 2019       |

We will support Ubuntu binaries 2 years after the official LTS support has ended to allow customers with extended support to continue using Relay.

Windows and macOS binaries are built using GitHub Runners. We will support the versions for those Operating Systems as long as GitHub supports them.

## [Example Configuration](#example-configuration)

This example configuration sets up basic logging and metrics settings, as well as changes the default concurrency level.

```yaml
---
relay:
  # The upstream hostname is taken from any of your DSNs.
  # Go to your Project Settings, and then to "Client Keys (DSN)" to see them.
  upstream: https://o0.ingest.sentry.io.
  host: 0.0.0.0
  port: 3000
logging:
  level: info
  format: json
metrics:
  statsd: 127.0.0.1:8126
  prefix: relay
limits:
  # Base size of various internal thread pools. Defaults to the number of logical CPU cores
  max_thread_count: 8
```

See the [Configuration Options](/product/relay/options/) page for detailed descriptions of all available options.

## [Performance Tuning](#performance-tuning)

Relay provides a variety of [Configuration Options](/product/relay/options/). Changing some of the options has more impact on Relay's behavior than others. The following list identifies a few options you should check first when you want to tune Relay to your organization's environment and workload:

* `limits.max_concurrent_requests` (default: 100)

  Number of concurrent requests your Relay instance can send to the upstream (Sentry). If your event volume or connection latency to Sentry are high, you can increase this value to gain additional throughput, though that increase will be at the expense of additional network connections.

* `cache.event_buffer_size` (default: 1000)

  How many events Relay can buffer in its local queue before it starts rejecting new events. Increasing this value will also increase Relay's potential memory consumption when, for example, network issues prevent Relay from forwarding the received messages to Sentry.

* `cache.event_expiry` (in seconds, default: 600)

  How long Relay can keep buffered events in memory before dropping them. You can increase this value if you anticipate when your Relay may need to keep events in memory for longer than the default value.

* `cache.project_expiry` (in seconds, default: 300)

  To stay operational, Relay regularly fetches project configurations from the Sentry upstream. This setting controls how often Relay fetches that configuration. You can decrease this value to make the configuration propagation more frequent. For example, if you later change data scrubbing options in your project settings in Sentry, your Relay instance will become aware of those changes faster.

* `cache.project_grace_period` (in seconds, default: 0)

  How long a project configuration can still be used after having expired. Increasing this value may help when the upstream is unreachable; for example, due to network issues.

## [Request Routing](#request-routing)

SDKs communicate with Sentry on a set of endpoints. Relay provides the same API to become a seamless drop-in replacement. This requires a set of endpoints to be accessible:

* `/api/<project-id>/envelope/`
* `/api/<project-id>/minidump/`
* `/api/<project-id>/security/`
* `/api/<project-id>/store/`
* `/api/<project-id>/unreal/<sentry-key>/`
* `/api/<project-id>/nel/`
* `/api/<project-id>/csp-report/`
* `/api/<project-id>/cron/<monitor-slug>/`
* `/api/<project-id>/cron/<monitor-slug>/<sentry-key>/`

Depending on the SDK or client, requests to these endpoints are performed with compressed content-encoding or chunked transfer-encoding. Depending on the infrastructure in front of Relay, please check the following HTTP headers are set correctly:

* `Host`: to the public host name of this Relay
* `X-Forwarded-For`: to the client IP address
* `X-Sentry-Auth`: to the value provided by the client

Proxies often set a default maximum body size for requests. Especially native crash reports and attachments can exceed these limits. We recommend to configure a maximum client body size of *100MB*.

Internally, Relay makes requests to the configured upstream to forward data and retrieve project configuration. We **highly recommend against** constraining these requests. At present, Relay makes requests to the following endpoints for basic operation:

* All of the above endpoints
* `/api/0/relays/projectconfigs/`
* `/api/0/relays/publickeys/`
* `/api/0/relays/register/challenge/`
* `/api/0/relays/register/response/`
