How to Deploy and Operate Sentry Relay for Enterprise Data Security

Overview

The article reviews the operational guide for running Sentry Relay in a self‑hosted environment and forwarding events to sentry.io.

Deployment Recommendations

Use the official Docker image getsentry/Relay from Docker Hub, which includes a Git revision identifier.

Run at least two Relay containers behind a reverse proxy such as HAProxy or Nginx to improve availability and simplify updates.

Configure logging, metrics, and health checks as described in the Sentry documentation.

System Requirements and Suggestions

CPU : x86‑64 architecture, multi‑core. For workloads exceeding 100 requests per second, use at least four cores; adjust limits.max_thread_count if needed.

Memory : Minimum 2 GB RAM per Relay container.

Network : Sufficient bandwidth for compressed upstream traffic; keep round‑trip latency below 5 seconds.

Storage : No persistent disk required.

Example Configuration

The following YAML sets basic logging, metrics, and a higher default thread count.

---
relay:
  # The upstream hostname is taken from any of your DSNs.
  # Go to your Project Settings, and then to "Client Keys (DSN)" to see them.
  upstream: https://___ORG_INGEST_DOMAIN___.
  host: 0.0.0.0
  port: 3000
logging:
  level: info
  format: json
metrics:
  statsd: 127.0.0.1:8126
  prefix: relay
limits:
  # Base size of various internal thread pools. Defaults to the number of logical CPU cores
  max_thread_count: 8

See the full configuration reference page for all options.

Performance Tuning

limits.max_concurrent_requests

(default 100): controls how many concurrent requests each Relay can send upstream. Increasing it raises throughput at the cost of more network connections. cache.event_buffer_size (default 1000): number of events buffered locally before rejecting new ones. Raising it can help during network outages but increases memory usage. cache.event_expiry (seconds, default 600): how long buffered events are kept before being dropped. cache.project_expiry (seconds, default 300): frequency of fetching project configuration from Sentry; lowering it makes config propagation faster. cache.project_grace_period (seconds, default 0): how long stale project config can be used when the upstream is unreachable.

Request Routing

Relay must be able to reach the following Sentry endpoints:

/api/<project-id>/envelope/

/api/<project-id>/minidump/

/api/<project-id>/security/

/api/<project-id>/store/

/api/<project-id>/unreal/

Requests use either compressed content‑encoding or chunked transfer‑encoding. Ensure the following HTTP headers are set correctly: Host: the public hostname of the Relay. X-Forwarded-For: client IP address. X-Sentry-Auth: value provided by the client.

Proxies usually set a default maximum body size; for native crash reports and attachments we recommend configuring the maximum client body size to 100 MB .

Internal Operations

Relay forwards data to the configured upstream and periodically fetches project configuration. It is strongly recommended not to limit these internal requests. The internal endpoints used are:

/api/0/relays/projectconfigs/

/api/0/relays/publickeys/

/api/0/relays/register/challenge/

/api/0/relays/register/response/