Configuration Options

Configuration for Relay is recorded either in the file .relay/config.yml, or when noted, can be overridden through an environment variable. 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".` Important Relay 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:

500B
1kB (1,000 bytes)
1KB or 1KiB (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. Warning On `debug` and `trace` levels, Relay emits extremely verbose messages which can have severe impact on application performance.
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").

Suggest an edit to this page | Contribute to Docs | Report a problem

Docs

Product

Data Management

Account Management

Relay

sentry-cli

Security and Legal

Integrations

Additional Resources

Configuration Options

Important

Warning