doc(relay): Health & spooler options (#15850)

Author: jjbayer

docs/product/relay/options.mdx

@@ -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.
@@ -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