Configuration Options
Configure Relay to suit the needs of your organization.
Configuration for Relay is typically recorded in the file .relay/config.yml (relative to the working directory). Configuration options can be overridden through environment variables. To change the config location, pass the --config option to any Relay command:
Copied
❯ ./relay run --config /path/to/folder
All configuration keys are snake_case.
Credentials can be initiated as described in the getting started page, but can be overridden by setting the following environment variables:
- Secret key:
RELAY_SECRET_KEY. - Public key:
RELAY_PUBLIC_KEY. - ID:
RELAY_ID.
| key | type | value | description |
|---|---|---|---|
| relay.mode | String | default value: managed possible values: managed, static, proxy, capture optional: false | Controls how Relay obtains the project configuration for events. For detailed explanation of these modes, see Relay Modes. Environment variable: "RELAY_MODE." |
| relay.upstream | String | default value: https://sentry.io optional: false | Fully qualified URL of the upstream Relay or Sentry instance. Environment variable: "RELAY_UPSTREAM_URL". ImportantRelay doesn't check for cycles. Don't set this option to an endpoint that will cause events to be cycled back here. |
| relay.host | String | default value: 0.0.0.0 in Docker, otherwise 127.0.0.1 optional: false | The host to which Relay should bind (network interface). Environment variable: "RELAY_HOST". |
| 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. |
These settings control network-related configurations.
| key | type | value | description |
|---|---|---|---|
| http.timeout | Integer | default: 5 | Timeout for upstream requests in seconds. This timeout covers the period of time from when a request is sent to when response headers are received. It doesn’t cover the connection process, handshakes, or reading of the response body. |
| http.connection_timeout | Integer | default: 3 | Timeout for establishing connections with the upstream in seconds. Relay reuses connections when the upstream supports connection keep-alive. Connections are retained for a maximum of 75 seconds of activity or 15 seconds of inactivity. |
| http.max_retry_interval | Integer | default: 60 | Maximum interval between failed request retries in seconds. |
| http.host_header | String | default: null | Custom HTTP Host header to be sent to the upstream. |
These settings fine tune caching of project states.
| key | type | value | description |
|---|---|---|---|
| cache.project_expiry | Integer | default: 300 (5 minutes) | The cache timeout for project configurations in seconds. Irrelevant if you use the "simple proxy mode", where your project config is stored in local files. |
| cache.project_grace_period | Integer | default: 0 (seconds) | The number of seconds you can continue using this project configuration after cache expiry while a new state is being fetched. This is added on top of cache.project_expiry and cache.miss_expiry. |
| cache.relay_expiry | Integer | default: 3600 (1 hour) | The cache timeout for downstream Relay info (public keys) in seconds. This is only relevant if you plan to connect further Relays to this one. |
| cache.envelope_expiry | Integer | default: 600 (10 minutes) | The maximum amount of time Relay buffers incoming payloads in its cache in case of network issues or backlogs. This applies to all types of data sent to Relay, including events, attachments, and sessions. See also cache.envelope_buffer_size. |
| cache.miss_expiry | Integer | default: 60 (1 minute) | The cache timeout for non-existing entries. |
| cache.batch_interval | Integer | default: 100 (100 milliseconds) | The buffer timeout for batched queries before they are sent upstream in milliseconds. |
| cache.batch_size | Integer | default: 500 | The maximum number of project configs to be fetched from Sentry at once. |
| cache.file_interval | Integer | default: 10 (10 seconds) | The interval for watching local cache override files in seconds. |
| cache.envelope_buffer_size | Integer | default: 1000 | The maximum number of incoming payloads that are buffered if network issues or backlogs happen. This applies to all types of data sent to Relay, including events, attachments, and sessions. See also cache.envelope_expiry. |
| cache.eviction_interval | Integer | default: 60 (seconds) | The interval for evicting outdated project configs from memory. |
| 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.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. |
These settings control HTTP-related limits. All values are either integers, or are human-readable strings of a number and a human-readable unit, such as:
500B1kB(1,000 bytes)1KBor1KiB(1,024 bytes)1MB(1,000,000 bytes)1MiB(1,048,576 bytes)
| key | type | value | description |
|---|---|---|---|
| limits.max_concurrent_requests | Integer | default: 100 | The maximum number of concurrent connections upstream. If supported by the upstream, Relay supports connection keep-alive. |
| limits.max_concurrent_queries | Integer | default: 5 | The maximum number of queries that can be sent concurrently from Relay upstream before Relay starts buffering requests. Queries are all requests made upstream for obtaining information and explicitly exclude event submission. The concurrency of queries is additionally constrained by max_concurrent_requests. |
| limits.max_event_size | String | default: 1MiB | The maximum payload size for events. |
| limits.max_attachment_size | String | default: 50MiB | The maximum attachment size. |
| limits.max_attachments_size | String | default: 50MiB | The maximum combined size for all attachments in an envelope or request. |
| limits.max_envelope_size | String | default: 50MiB | The maximum payload size for an entire envelope. Individual limits still apply. |
| limits.max_session_count | Integer | default: 100 | The maximum number of session items per envelope. |
| limits.max_api_payload_size | String | default: 20MiB | The maximum payload size for general API requests. |
| limits.max_api_file_upload_size | String | default: 40MiB | The maximum payload size for file uploads and chunks. |
| limits.max_api_chunk_upload_size | String | default: 100MiB | The maximum payload size for chunks. |
| limits.max_thread_count | Integer | default: number of cpus | The maximum number of threads spawned for each CPU and web worker. The total number of threads spawned will roughly be 2 * limits.max_thread_count + N, where N is a fixed set of management threads. |
| limits.query_timeout | Integer | default: 30 (seconds) | The maximum number of seconds a query can take across retries. Individual requests have lower timeouts. |
| limits.shutdown_timeout | Integer | default: 10 (seconds) | The maximum number of seconds you'd have to wait for pending events after receiving a shutdown signal. Environment variable: "SHUTDOWN_TIMEOUT". |
| key | type | value | description |
|---|---|---|---|
| logging.level | String | default: info possible values: off, error, warn, info, debug, trace. | The log level for the relay. WarningOn debug and trace levels, Relay emits extremely verbose messages which can have severe impact on application performance. Environment variable: "RELAY_LOG_LEVEL" |
| logging.log_failed_payloads | Boolean | default: false | Full event payloads logs of failed events, added to the log stream. |
| logging.format | String | default: auto possible values: auto, pretty, simplified, json | Controls the log format. auto: Auto detect (pretty for TTY, simplified for other) pretty: Human readable format with colors simplified: Simplified human readable log output json: JSON records, suitable for logging software |
| logging.enable_backtraces | Boolean | default: true | Writes back traces for all internal errors to the log stream and includes them in Sentry errors. |
| key | type | value | description |
|---|---|---|---|
| metrics.statsd | String | optional: true | If set to a host/port string then metrics will be reported to this StatsD instance. |
| metrics.prefix | String | default: sentry.relay | The prefix that should be added to all metrics. |
| metrics.default_tags | Map of strings to strings | default: empty | A set of default tags that should be attached to all outgoing StatsD metrics. |
| metrics.hostname_tag | String | optional: true | If set, adds a tag of the given name and sets it to the hostname of the machine that is running Relay. This configuration is useful to distinguish multiple Relays. |
| metrics.buffering | Boolean | default: true | Determines if the emitted metrics will be buffered before sending to StatsD server. This generally improves performance, but comes with a caveat that with low traffic volume, metrics might take a few more seconds to propagate. |
| metrics.sample_rate | Float | default: 1.0 | Global sample rate for all emitted metrics. Should be between 0.0 and 1.0. If outside that range, the value will be normalized (negative values would become 0.0, positive larger than 1.0 would become 1.0). For instance, the value of 0.3 means that only 30% of the emitted metrics will be sent. Note that the implemented sampling approach isn't aware of metric types. For example, it won't rescale counter values when the sample rate is less than 1.0. |
Configures error reporting for errors happening within Relay. Disabled by default.
| key | type | value | description |
|---|---|---|---|
| sentry.enabled | Boolean | default: false | Determines whether to report internal errors to a separate DSN. false means that no internal errors will be sent, but will still be logged. |
| sentry.dsn | String | optional: true | Sentry DSN to which you can report internal Relay failures. We recommend setting this to a value that sends Relay errors directly to Sentry instead of sending them to itself first. |
By default, Relay does not include geographical location information in events. Set the MaxMind database file path to add GeoIP info in events.
| key | type | value | description |
|---|---|---|---|
| geoip.path | String | default: null | The path to the MaxMind GeoIP City database file. When set the additional GeoIP information will be added to the events. |
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").