Skip to content

doc(relay): Health & spooler options #15850

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jjbayer merged 4 commits into from
Dec 18, 2025
Merged

doc(relay): Health & spooler options #15850

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
82e966c
doc(relay): Health & spooler options
jjbayer Dec 17, 2025
0b1548c
format
jjbayer Dec 17, 2025
d5d23df
format
jjbayer Dec 17, 2025
8c7b02c
revert change to yarn.lock
jjbayer Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions docs/product/relay/options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,19 @@ Credentials can be initiated as described in the [getting started page](/product
| relay.port | Integer | default value: `3000` optional: `false` | The port to which Relay should bind for the unencrypted Relay HTTP server. `Environment variable: "RELAY_PORT".` |
| relay.override_project_ids | Boolean | optional: `true` | Overrides project identifiers stated in client DSNs with the identifier used at the Sentry upstream. By default, Relay rejects data on project ID mismatch. Set this setting to `true` when Relay redirects traffic to a migrated Sentry instance, such as when moving from self-hosted to Sentry SaaS. Validation of project identifiers can be safely omitted in these cases, and you can continue to use the previous DSNs in your services. |

## Health

Settings to control Relay's health checks.

After breaching one of the configured thresholds, Relay will
return an `unhealthy` status from its health endpoint.

| key | type | value | description |
| ----------------------- | ------- | --------------- | ----------- |
| health.max_memory_bytes | Integer | default: `null` | Maximum memory usage in bytes. |
| health.max_memory_percent | Float. | number between 0.0 and 1.0, default: 0.95 | Maximum memory usage as a percentage of available memory. |
| probe_timeout_ms | Integer | default: 900 | Health check probe timeout in milliseconds. Any probe exceeding the timeout will be considered failed. This limits the max execution time of Relay health checks. |

## HTTP

These settings control network-related configurations.
Expand Down Expand Up @@ -62,11 +75,10 @@ These settings fine tune caching of project states.

| key | type | value | description |
| ------------------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| spool.envelopes.path | String | default: `null` | The path to the spool file used to save envelopes to disk. If provided, enables on-disk spooling. Relay will create the directory structure if needed. Note that `~` is interpreted as a literal and not as the home directory. |
| spool.envelopes.max_memory_size | String | default: `500MB` | The maximum in-memory buffer for incoming envelopes. The buffer will be spooled to disk when the configured size is reached. |
| spool.envelopes.path | String | default: `null` | The path to the spool file used to save envelopes to disk. If provided, enables on-disk spooling. Relay will create the directory structure if needed. Note that `~` is interpreted as a literal and not as the home directory. | |
| spool.envelopes.max_disk_size | String | default: `500MB` | The maximum on-disk spool size. |
| spool.envelopes.max_connections | Integer | default: `20` | The maximum number of connections in the pool to manage on-disk spooling. |
| spool.envelopes.min_connections | Integer | default: `10` | The minimum number of connections in the pool to manage on-disk spooling. |
| spool.envelopes.max_envelope_delay_secs | Integer | default: `24 * 60 * 60` (24h) | Maximum time between receiving the envelope and processing it. When envelopes spend too much time in the buffer (e.g. because their project cannot be loaded), they are dropped.
| spool.envelopes.max_backpressure_memory_percent | Float | number between 0.0 and 1.0, default: 0.8 | The relative memory usage above which the buffer service will stop dequeueing envelopes. Only applies when `spool.envelopes.path` is set. This value should be lower than `health.max_memory_percent` to prevent flip-flopping. |

## Size Limits

Expand Down
Loading