Understanding Sentry Relay: Monitoring, Logging, and Metrics Collection

Logging

Relay writes logs to stderr at the INFO level by default. Example output when Relay starts:

INFO  relay::setup > launching relay from config folder .relay
INFO  relay::setup >   relay mode: managed
INFO  relay::setup >   relay id: cde0d72e-0c4e-4550-a934-c1867d8a177c
INFO  relay::setup >   log level: INFO

The log level can be changed via the options page.

Error reporting

Errors are recorded to the configured logger. To enable Sentry error reporting, add a sentry block to the Relay configuration file:

sentry:
  enabled: true
  dsn: <your_dsn>

Health checks

Relay exposes two HTTP endpoints to verify its operational state: GET /api/relay/healthcheck/live/ – tests whether Relay is running and listening for HTTP requests. GET /api/relay/healthcheck/ready/ – tests whether Relay has passed upstream validation and is ready to operate.

When successful both endpoints return 200 OK with the JSON payload:

{
  "is_healthy": true
}

Metrics configuration

Metrics can be sent to a StatsD server by setting the metrics.statsd key to an ip:port tuple. The address of the StatsD server is configurable, and a prefix can be added to all metric names.

Example configuration

metrics:
  # Endpoint of your StatsD server
  statsd: 127.0.0.1:8126
  # Prefix all metric names with this string
  prefix: mycompany.relay

Relay collected metrics

Relay emits a large set of metrics. Each metric is identified by a name, a type, and a description. The most relevant metrics are listed below.

Event processing

event.accepted (Counter)

– number of envelopes accepted in the current interval (passed rate limiting and filters). event.corrupted (Counter) – number of events with corrupted (unprintable) environment or release attributes. event.processing_time (Timer) – total time in milliseconds spent processing an envelope synchronously, covering deserialization, PII scrubbing, and serialization. Sub‑timers include:

event_processing.deserialize

event_processing.pii

event_processing.serialization

event_processing.process

event_processing.filtering

event_processing.rate_limiting

event.rejected (Counter)

– number of envelopes rejected in the current interval due to format errors, filtering, or rate limiting. Reasons are available via events.outcomes. event.total_time (Timer) – total time in milliseconds from when an envelope is received until it is fully processed and handed off upstream. event.wait_time (Timer) – time between receipt of a request and the start of synchronous processing, indicating backlog.

Queue metrics

event.queue_size (Histogram)

– current number of envelopes in the processing queue. Queue size is configurable via cache.event_buffer_size. event.queue_size.pct (Histogram) – queue occupancy as a fraction (0 = empty, 1 = full). http_queue.size (Histogram) – number of upstream HTTP requests waiting to be sent. Requests are tagged with priority ( high or low). Concurrency limits are set with limits.max_concurrent_requests and limits.max_concurrent_queries.

Size metrics

event.size_bytes.raw (Histogram)

– size in bytes of the raw HTTP request body as seen by Relay (envelope size, JSON store body, or multipart upload). Maximum request body size is configurable via limits.max_envelope_size. event.size_bytes.uncompressed (Histogram) – size in bytes after Relay decompresses and decodes the payload.

Outcome metrics

events.outcomes (Counter)

– counts of envelope outcomes tagged by outcome ( filtered, rate_limited, invalid), reason (specific rule or mechanism), and to (destination, e.g., kafka or http).

Project cache metrics

project_cache.hit (Counter)

– successful cache lookups. project_cache.miss (Counter) – cache misses that trigger an immediate upstream request. project_cache.eviction (Counter) – number of stale projects evicted from the in‑memory cache (interval set by cache.eviction_interval). project_cache.size (Histogram) – current number of project states stored in memory (no hard limit). project_state.request (Counter) – number of HTTP requests made to fetch project state. Batching is controlled by limits.max_concurrent_queries and cache.batch_size. Duration of each batch is reported by project_state.request.duration. project_state.pending (Histogram) – number of projects waiting in the cache for a state update.

Upstream request metrics

upstream.requests.duration (Timer)

– total time in milliseconds to send a request to upstream and process the response. Tagged by: result – success, response_error, payload_failed, send_failed, rate_limited,

invalid_json

route

– upstream endpoint status-code – HTTP status code or "-" if unavailable retries – 0, 1, 2, few (3‑10), many (>10) upstream.retries (Histogram) – number of retry attempts per upstream request, with the same tags. upstream.network_outage (Gauge) – 0 for normal operation, 1 for network outage.

Other notable metrics

server.starting (Counter)

– number of times the Relay server has started (useful for detecting unexpected restarts). unique_projects (Set) – number of active projects in the current time slice. scrubbing.attachments.duration (Timer) – time spent cleaning attachments. scrubbing.minidumps.duration (Timer) – time spent parsing and cleaning minidumps, tagged by status ( ok, error, n/a).