Understanding Sentry Relay Configuration Options

Relay configuration is stored in .relay/config.yml. Use the --config option to specify an alternate location, e.g.:

❯ ./relay run --config /path/to/folder

Relay

relay.mode

String, default: managed . Possible values: managed , static , proxy , capture . Controls how Relay obtains project configuration.

relay.upstream

String, default: https://sentry.io . Fully‑qualified URL of the upstream Relay or Sentry instance. Relay does not check for loops; do not set to an endpoint that would cause events to loop back.

relay.host

String, default: 0.0.0.0 in Docker, otherwise 127.0.0.1 . Network interface Relay should bind to.

relay.port

Integer, default: 3000 . Port for the unencrypted Relay HTTP server.

relay.tls_port

Integer, optional. Port for the encrypted Relay HTTPS server (e.g., 3001 ). If set, the HTTP server on relay.port still runs.

relay.tls_identity_path

String, optional. Filesystem path to the DER‑encoded PKCS12 identity for the HTTPS server, evaluated relative to the current working directory (e.g., relay_dev.pfx ).

relay.tls_identity_password

String, optional. Password for the PKCS12 archive referenced by relay.tls_identity_path .

HTTP

http.timeout

Integer, default: 5 seconds. Timeout for upstream requests (from sending the request to receiving response headers). Does not include connection handshake or response body reading.

http.connection_timeout

Integer, default: 3 seconds. Timeout for establishing a connection to the upstream, including SSL handshake. Connections are kept alive for up to 75 seconds and idle for 15 seconds.

http.max_retry_interval

Integer, default: 60 seconds. Maximum interval between retries of failed requests.

http.host_header

String, default: null . Custom HTTP Host header to send to the upstream.

Caching

cache.project_expiry

Integer, default: 300 (5 minutes). Cache timeout for project configuration. Irrelevant in "simple proxy mode" where config is stored locally.

cache.project_grace_period

Integer, default: 0 seconds. Seconds to keep using a project config after it expires while fetching a fresh one.

cache.relay_expiry

Integer, default: 3600 (1 hour). Cache timeout for downstream Relay public keys; relevant only when multiple Relays connect to this Relay.

cache.envelope_expiry

Integer, default: 600 (10 minutes). Maximum time Relay buffers incoming payloads during network issues or backlog.

cache.miss_expiry

Integer, default: 60 (1 minute). Cache timeout for missing entries.

cache.batch_interval

Integer, default: 100 (100 ms). Buffer timeout before sending batched queries upstream.

cache.batch_size

Integer, default: 500 . Maximum number of project configs fetched in a single batch from Sentry.

cache.file_interval

Integer, default: 10 (10 seconds). Interval for monitoring local cache overlay files.

cache.envelope_buffer_size

Integer, default: 1000 . Maximum number of incoming payloads buffered during network problems or backlog.

cache.eviction_interval

Integer, default: 60 seconds. Interval for evicting stale project configs from memory.

Size Limits

Values may be integers or human‑readable strings such as 500B, 1kB, 1MiB, etc.

limits.max_concurrent_requests

Integer, default: 100 . Maximum concurrent connections to the upstream; keep‑alive is used if supported.

limits.max_concurrent_queries

Integer, default: 5 . Maximum concurrent queries sent to the upstream before buffering. Queries exclude event submissions and are also limited by max_concurrent_requests .

limits.max_event_size

String, default: 1MiB . Maximum payload size for an event.

limits.max_attachment_size

String, default: 50MiB . Maximum size for a single attachment.

limits.max_attachments_size

String, default: 50MiB . Maximum combined size of all attachments in an envelope or request.

limits.max_envelope_size

String, default: 50MiB . Maximum payload size for an entire envelope (individual limits still apply).

limits.max_api_payload_size

String, default: 20MiB . Maximum payload size for generic API requests.

limits.max_api_file_upload_size

String, default: 40MiB . Maximum payload size for file uploads and chunks.

limits.max_api_chunk_upload_size

String, default: 100MiB . Maximum payload size for a single chunk.

limits.max_thread_count

Integer, default: number of CPUs. Maximum threads generated per CPU and web worker. Total threads ≈ 2 * limits.max_thread_count + N , where N is a fixed set of management threads.

limits.query_timeout

Integer, default: 30 seconds. Maximum seconds allowed for query retries; individual request timeout is shorter.

limits.max_connection_rate

Integer, default: 256 . Maximum number of connections that can be created to Relay at once.

limits.max_pending_connections

Integer, default: 2048 . Maximum pending connections to Relay (POSIX listen(2) backlog).

limits.max_connections

Integer, default: 25000 . Maximum inbound connections opened by Relay.

limits.shutdown_timeout

Integer, default: 10 seconds. Maximum seconds to wait for pending events after receiving a shutdown signal.

Logging

logging.level

String, default: info . Options: off , error , warn , info , debug , trace . debug and trace produce very verbose output that can impact performance.

logging.log_failed_payloads

Boolean, default: false . Whether to log the full payload of failed events.

logging.format

String, default: auto . Controls log format. Options: auto (detects TTY), pretty (colored human‑readable), simplified (human‑readable), json (JSON for log processors).

logging.enable_backtraces

Boolean, default: true . When enabled, internal error backtraces are written to the log stream and included in Sentry errors.

StatsD Metrics

metrics.statsd

String, optional. Host/port of a StatsD instance to which metrics will be reported.

metrics.prefix

String, default: sentry.relay . Prefix added to all metrics.

metrics.default_tags

Map of strings to strings, default: empty. Default tags attached to all outgoing StatsD metrics.

metrics.hostname_tag

String, optional. If set, adds a tag with the given name containing the hostname of the machine running Relay, useful for distinguishing multiple Relays.

metrics.buffering

Boolean, default: true . Whether to buffer metrics before sending to the StatsD server. Buffering improves performance but may add a few seconds of latency under low traffic.

metrics.sample_rate

Float, default: 1.0 . Global sampling rate for all emitted metrics (0.0–1.0). Values outside the range are clamped. For example, 0.3 means only 30 % of metrics are sent.

Internal Error Reporting

sentry.enabled

Boolean, default: false . Whether to report internal errors to a separate DSN. false means errors are not sent but are still logged.

sentry.dsn

String, optional. DSN to which internal Relay failures are reported. It is recommended to use a DSN that does not route errors back to the same Relay.