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.

keytypevaluedescription
relay.modeStringdefault value: managed possible values: managed, static, proxy, capture optional: falseControls how Relay obtains the project configuration for events. For detailed explanation of these modes, see Relay Modes. Environment variable: "RELAY_MODE."
relay.upstreamStringdefault value: https://sentry.io optional: falseFully qualified URL of the upstream Relay or Sentry instance. Environment variable: "RELAY_UPSTREAM_URL".
relay.hostStringdefault value: 0.0.0.0 in Docker, otherwise 127.0.0.1 optional: falseThe host to which Relay should bind (network interface). Environment variable: "RELAY_HOST".
relay.portIntegerdefault value: 3000 optional: falseThe port to which Relay should bind for the unencrypted Relay HTTP server. Environment variable: "RELAY_PORT".
relay.override_project_idsBooleanoptional: trueOverrides 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.

keytypevaluedescription
http.timeoutIntegerdefault: 5Timeout 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_timeoutIntegerdefault: 3Timeout 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_intervalIntegerdefault: 60Maximum interval between failed request retries in seconds.
http.host_headerStringdefault: nullCustom HTTP Host header to be sent to the upstream.

These settings fine tune caching of project states.

keytypevaluedescription
cache.project_expiryIntegerdefault: 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_periodIntegerdefault: 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_expiryIntegerdefault: 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_expiryIntegerdefault: 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_expiryIntegerdefault: 60 (1 minute)The cache timeout for non-existing entries.
cache.batch_intervalIntegerdefault: 100 (100 milliseconds)The buffer timeout for batched queries before they are sent upstream in milliseconds.
cache.batch_sizeIntegerdefault: 500The maximum number of project configs to be fetched from Sentry at once.
cache.file_intervalIntegerdefault: 10 (10 seconds)The interval for watching local cache override files in seconds.
cache.envelope_buffer_sizeIntegerdefault: 1000The 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_intervalIntegerdefault: 60 (seconds)The interval for evicting outdated project configs from memory.

keytypevaluedescription
spool.envelopes.pathStringdefault: nullThe 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_sizeStringdefault: 500MBThe maximum in-memory buffer for incoming envelopes. The buffer will be spooled to disk when the configured size is reached.
spool.envelopes.max_disk_sizeStringdefault: 500MBThe maximum on-disk spool size.
spool.envelopes.max_connectionsIntegerdefault: 20The maximum number of connections in the pool to manage on-disk spooling.
spool.envelopes.min_connectionsIntegerdefault: 10The 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)
keytypevaluedescription
limits.max_concurrent_requestsIntegerdefault: 100The maximum number of concurrent connections upstream. If supported by the upstream, Relay supports connection keep-alive.
limits.max_concurrent_queriesIntegerdefault: 5The 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_sizeStringdefault: 1MiBThe maximum payload size for events.
limits.max_attachment_sizeStringdefault: 50MiBThe maximum attachment size.
limits.max_attachments_sizeStringdefault: 50MiBThe maximum combined size for all attachments in an envelope or request.
limits.max_envelope_sizeStringdefault: 50MiBThe maximum payload size for an entire envelope. Individual limits still apply.
limits.max_session_countIntegerdefault: 100The maximum number of session items per envelope.
limits.max_api_payload_sizeStringdefault: 20MiBThe maximum payload size for general API requests.
limits.max_api_file_upload_sizeStringdefault: 40MiBThe maximum payload size for file uploads and chunks.
limits.max_api_chunk_upload_sizeStringdefault: 100MiBThe maximum payload size for chunks.
limits.max_thread_countIntegerdefault: number of cpusThe 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_timeoutIntegerdefault: 30 (seconds)The maximum number of seconds a query can take across retries. Individual requests have lower timeouts.
limits.shutdown_timeoutIntegerdefault: 10 (seconds)The maximum number of seconds you'd have to wait for pending events after receiving a shutdown signal. Environment variable: "SHUTDOWN_TIMEOUT".

keytypevaluedescription
logging.levelStringdefault: info possible values: off, error, warn, info, debug, trace.The log level for the relay. . Environment variable: "RELAY_LOG_LEVEL"
logging.log_failed_payloadsBooleandefault: falseFull event payloads logs of failed events, added to the log stream.
logging.formatStringdefault: auto possible values: auto, pretty, simplified, jsonControls 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_backtracesBooleandefault: trueWrites back traces for all internal errors to the log stream and includes them in Sentry errors.

keytypevaluedescription
metrics.statsdStringoptional: trueIf set to a host/port string then metrics will be reported to this StatsD instance.
metrics.prefixStringdefault: sentry.relayThe prefix that should be added to all metrics.
metrics.default_tagsMap of strings to stringsdefault: emptyA set of default tags that should be attached to all outgoing StatsD metrics.
metrics.hostname_tagStringoptional: trueIf 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.bufferingBooleandefault: trueDetermines 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_rateFloatdefault: 1.0Global 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.

keytypevaluedescription
sentry.enabledBooleandefault: falseDetermines whether to report internal errors to a separate DSN. false means that no internal errors will be sent, but will still be logged.
sentry.dsnStringoptional: trueSentry 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.

keytypevaluedescription
geoip.pathStringdefault: nullThe 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").