diff --git a/src/docs/product/relay/getting-started.mdx b/src/docs/product/relay/getting-started.mdx index 9b8abb21c9bb7..114843b3220c7 100644 --- a/src/docs/product/relay/getting-started.mdx +++ b/src/docs/product/relay/getting-started.mdx @@ -21,7 +21,7 @@ Releases](https://github.com/getsentry/relay/releases). A Docker image is provid To create the initial configuration, use Relay's `relay config init` command, which puts configuration files in the `.relay` folder under the current working -directory. +directory. @@ -33,6 +33,14 @@ container and copying in the files. ```shell {tabTitle:Run in Docker} +# Adjust permissions for the configuration directory +docker run --rm -it \ + -v $(pwd)/config/:/work/.relay/ \ + --entrypoint bash \ + getsentry/relay \ + -c 'chown -R relay:relay /work/.relay' + +# Generate the configuration docker run --rm -it \ -v $(pwd)/config/:/work/.relay/ \ getsentry/relay \ @@ -66,7 +74,18 @@ _"create custom config"_ and customizing these parameters: Settings are recorded in `.relay/config.yml`. Note that all configuration values are optional and default to these settings: -```yaml +```yaml {tabTitle:Run in Docker} +relay: + mode: managed + upstream: "https://sentry.io/" + host: 0.0.0.0 + port: 3000 + tls_port: ~ + tls_identity_path: ~ + tls_identity_password: ~ +``` + +```yaml {tabTitle:Run Executable} relay: mode: managed upstream: "https://sentry.io/" @@ -96,7 +115,7 @@ A typical credentials file is similar to this example: ```json { "secret_key": "5gkTAfwOrJ0lMy9aOAOmHKO1k6gd8ApYkAInmg5VfWk", - "public_key": "fQzvlvqLM2pJwLDwM_sXD2Lk5swzx-Oml4WhsOquon4", + "public_key": "nDJI79SbEYH9-8NEJAI7ezrgYfoIPW3Bnkg00k1z0fA", "id": "cde0d72e-0c4e-4550-a934-c1867d8a177c" } ``` @@ -144,10 +163,6 @@ This process registers Relay with Sentry so it is ready to send messages. See ## Running Relay -You can either run the Relay binary directly or using a Docker image. - -### Running Relay Directly - After registering Relay with Sentry, it is ready to run: ```shell {tabTitle:Run in Docker} @@ -167,17 +182,19 @@ Under default configuration, Relay emits log output similar to: ``` INFO relay::setup > launching relay from config folder .relay INFO relay::setup > relay mode: managed - INFO relay::setup > relay id: f2119bc9-9a9b-4531-826b-24e9794902f2 - INFO relay::setup > public key: QPBITKKtKUuEZGGbPke8iufEXAcVrEv6nmWrkRtc3l8 + INFO relay::setup > relay id: cde0d72e-0c4e-4550-a934-c1867d8a177c + INFO relay::setup > public key: nDJI79SbEYH9-8NEJAI7ezrgYfoIPW3Bnkg00k1z0fA ... INFO relay_server::actors::upstream > relay successfully registered with upstream ``` +Refer to the [Logging](/product/relay/monitoring/#logging) page for more information on how to configure Relay's logging. + If you moved your config folder (for example, for security reasons), use the `--config` option to specify the location: ```shell {tabTitle:Run in Docker} docker run --rm -it \ - -v $(pwd)/config/:/work/.relay/ \ + -v $(pwd)/config/:/etc/relay/ \ -p 3000:3000 \ getsentry/relay \ run --config /etc/relay/ @@ -187,66 +204,41 @@ docker run --rm -it \ ./relay run --config /etc/relay/ ``` -## Logging - -Once Relay is running, you will receive `INFO` messages, such as: - -``` -INFO relay::setup > launching relay from config folder .relay -INFO relay::setup > relay mode: managed -INFO relay::setup > relay id: f2119bc9-9a9b-4531-826b-24e9794902f2 -INFO relay::setup > log level: INFO -``` - -This example displays the default logging level, which you can modify so it displays either more or less information. For details about configuring logging please see [Logging](/product/relay/options/#logging) on the options page. - -## Health Checks - -Relay provides two URLs for checking system status: - -- `GET /api/relay/healthcheck/live/`: Tests if Relay is running and listening to - HTTP requests. -- `GET /api/relay/healthcheck/ready/`: Tests if Relay is authenticated with the - upstream and operating normally. - -In case of success, both endpoints return a _200 OK_ response: - -```json -{ - "is_healthy": true -} -``` - ## Sending a Test Event -Once Relay is running and authenticated with Sentry, send a test event. +Once Relay is running and authenticated with Sentry, send a test event to one of the projects in your organization. -Get the DSN of your project by navigating to _Project Settings > Client Keys -(DSN)_, which looks similar to: +Get the DSN of your project by navigating to your project settings at _Settings > Projects > {YOUR_PROJECT_NAME} > Client Keys (DSN)_, and select one of the existing DSNs, which looks similar to: -``` -https://12345abcdb1e4c123490ecec89c1f199@o1.ingest.sentry.io/2244 -``` +`https://12345abcdef10111213141516171819@o1.ingest.sentry.io/2345` Next, replace parts of the DSN to match the address at which Relay is reachable. For instance, if Relay listens at `http://localhost:3000`, change the protocol and host of the DSN to: -``` -http://12345abcdb1e4c123490ecec89c1f199@localhost:3000/2244 -``` +

+ + http + ://12345abcdef10111213141516171819@ + localhost:3000 + /2345 + +

Use the new DSN in your SDK configuration. To test this, you can send a message -with `sentry-cli`: +with `sentry-cli` ([installation instructions](/cli/installation/)): ```shell -export SENTRY_DSN='http://12345abcdb1e4c123490ecec89c1f199@127.0.0.1:3000/2244' +export SENTRY_DSN='http://12345abcdef10111213141516171819@127.0.0.1:3000/2345' sentry-cli send-event -m 'A test event' ``` In a few seconds, the event should appear in the issues stream in your project. -## Advanced Configuration - +## Next Steps + +- **[Learn more about our Operating Guidelines](/product/relay/operating-guidelines/)** + +With a working Relay instance, you can both monitor and scale your Relay setup. diff --git a/src/docs/product/relay/index.mdx b/src/docs/product/relay/index.mdx index db9a1487bb82f..c49638112350e 100644 --- a/src/docs/product/relay/index.mdx +++ b/src/docs/product/relay/index.mdx @@ -10,7 +10,7 @@ Sentry Relay offers enterprise-grade data security by providing a standalone ser Relay is specifically designed to: -- Scrub personal information in a central place prior to sending it to Sentry, adding to the places Sentry already scrubs PII +- Scrub personally identifiable information (PII) in a central place prior to sending it to Sentry - Improve event response time in regions with low bandwidth or limited connectivity - Act as an opaque proxy for organizations that restrict all HTTP communication to a custom domain name @@ -63,6 +63,6 @@ Relay responds very quickly to requests. Installing Relay close to your infrastr By default, SDKs need to be configured with a Data Source Name (DSN) that points to `sentry.io`. If you need to restrict all HTTP communication to a custom domain name, Relay can act as an opaque proxy that reliably forwards events to Sentry. -## Configuration +## Next Steps diff --git a/src/docs/product/relay/metrics.mdx b/src/docs/product/relay/metrics.mdx deleted file mode 100644 index 528dbccc07135..0000000000000 --- a/src/docs/product/relay/metrics.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Errors and Metrics -description: "Enable error reporting to your project in Sentry." -sidebar_order: 3 -redirect_from: - - /meta/relay/metrics/ ---- -By default, Relay logs errors to the configured logger. You can enable error -reporting to your project in Sentry in the Relay configuration file: - -```yaml -sentry: - enabled: true - dsn: -``` - -## Configuration - -Stats can be submitted to a StatsD server by configuring the `metrics` key. The key -can be set to an `ip:port` tuple: - -```yaml -metrics: - statsd: 127.0.0.1:8126 - prefix: mycompany.relay -``` - -`statsd` - -: Configures the host and port of the StatsD client. We recommend running a - StatsD client on the same host as Relay for performance reasons. - -`prefix` - -: Configures a prefix that is prepended to all reported metrics. By default, all - metrics are reported with a `"sentry.relay"` prefix. - -`hostname_tag` - -: 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 separate multiple Relays. For example, setting this to: - - ```yaml - metrics: - hostname_tag: pod_name - ``` - - The above example adds a `"pod_name"` tag set to the host name for - every metric. - -## Metrics - -Relay emits the following metrics: - - diff --git a/src/docs/product/relay/monitoring/collected-metrics.mdx b/src/docs/product/relay/monitoring/collected-metrics.mdx new file mode 100644 index 0000000000000..43914f96d7b7f --- /dev/null +++ b/src/docs/product/relay/monitoring/collected-metrics.mdx @@ -0,0 +1,11 @@ +--- +title: Collected Metrics +description: "Learn what metrics Relay produces." +sidebar_order: 3 +redirect_from: + - /meta/relay/metrics/ +--- + +Relay collects the following metrics: + + diff --git a/src/docs/product/relay/monitoring/index.mdx b/src/docs/product/relay/monitoring/index.mdx new file mode 100644 index 0000000000000..4042c6befb408 --- /dev/null +++ b/src/docs/product/relay/monitoring/index.mdx @@ -0,0 +1,71 @@ +--- +title: Monitoring +description: "Configure logging, metrics, and error reporting for your Relay installation." +sidebar_order: 3 +redirect_from: + - /meta/relay/logging/ +--- +## Logging + +Relay produces logs to the standard error stream (`stderr`), with `INFO` logging level by default. +For example, after starting Relay you may see output such as this: + +``` +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 +``` + +This example displays the messages with the default logging level (`INFO`), which you can modify so it displays either more or less information. For details about configuring logging please see the [Logging](/product/relay/options/#logging) section on the options page. + +## Error Reporting + +By default, Relay logs errors to the configured logger. You can enable error +reporting to your project in Sentry in the Relay configuration file: + +```yaml +sentry: + enabled: true + dsn: +``` + +More information about available options and their meaning can be found [on the options page](/product/relay/options/#internal-error-reporting). + +## Health Checks + +Relay provides two URLs for checking system status: + +- `GET /api/relay/healthcheck/live/`: Tests if Relay is running and listening to + HTTP requests. +- `GET /api/relay/healthcheck/ready/`: Tests if Relay is authenticated with the + upstream and operating normally. + +Both endpoints return a _200 OK_ response when successful: + +```json +{ + "is_healthy": true +} +``` + +## Metrics + +You can submit stats to a StatsD server by configuring the `metrics.statsd` key to an `ip:port` tuple. +can be set to an `ip:port` tuple. + +### Example Configuration + +```yaml +metrics: + # Endpoint of your StatsD server + statsd: 127.0.0.1:8126 + # Prefix all metric names with this string + prefix: mycompany.relay +``` + +The options for configuring metrics reporting are documented on the [options page](/product/relay/options/#statsd-metrics). + +## Learn More + + diff --git a/src/docs/product/relay/best-practices.mdx b/src/docs/product/relay/operating-guidelines.mdx similarity index 50% rename from src/docs/product/relay/best-practices.mdx rename to src/docs/product/relay/operating-guidelines.mdx index 8b72bf08bb58b..465ebc45aa488 100644 --- a/src/docs/product/relay/best-practices.mdx +++ b/src/docs/product/relay/operating-guidelines.mdx @@ -4,6 +4,7 @@ description: "Learn about our guidelines for operation when self-hosting externa sidebar_order: 5 redirect_from: - /meta/relay/best-practices/ + - /product/relay/best-practices/ --- This page reviews our guidelines for operation when self-hosting external Relays, that is, Relays that run on your hardware and forward events to `sentry.io`. @@ -14,7 +15,7 @@ This page reviews our guidelines for operation when self-hosting external Relays - We recommend running at least two Relay instances (containers) with a reverse proxy (such as [HAProxy](https://www.haproxy.org/) or [Nginx](https://nginx.org)) in front of them for both improved availability and simplified Relay updates. -- To monitor your Relay setup, configure [Logging](/product/relay/#logging-and-healthcheck), [Metrics](/product/relay/metrics/), and [Health Checks](/product/relay/getting-started/#health-checks). +- To monitor your Relay setup, configure [Logging](/product/relay/monitoring/#logging), [Metrics](/product/relay/monitoring/#metrics), and [Health Checks](/product/relay/monitoring/#health-checks). ## System Requirements and Recommendations @@ -97,7 +98,7 @@ This example configuration sets up basic logging and metrics settings, as well a --- relay: # The upstream hostname is taken from any of your DSNs. - # Go to project Settings, and then to "Client Keys (DSN)" to see them. + # Go to your Project Settings, and then to "Client Keys (DSN)" to see them. upstream: https://o.ingest.sentry.io. host: 0.0.0.0 port: 3000 @@ -113,3 +114,62 @@ limits: ``` See the [Configuration Options](/product/relay/options/) page for detailed descriptions of all available options. + +## Performance Tuning + +Relay provides a variety of [Configuration Options](/product/relay/options/). Changing some of the options has more impact on Relay's behavior than others. +The following list identifies a few options you should check first when you want to tune Relay to your organization's environment and workload: + +- `limits.max_concurrent_requests` (default: 100) + + Number of concurrent requests your Relay instance can send to + the upstream (Sentry). If your event volume or connection latency to Sentry are high, you can increase this value to gain additional throughput, though that increase will be at the expense of additional network connections. + +- `cache.event_buffer_size` (default: 1000) + + How many events Relay can buffer in its local queue before it starts rejecting new events. + Increasing this value will also increase Relay's potential memory consumption when, for + example, network issues prevent Relay from forwarding the received messages to Sentry. + +- `cache.event_expiry` (in seconds, default: 600) + + How long Relay can keep buffered events in memory before dropping them. You can increase this value if you anticipate when your Relay may need to keep events in memory for longer than the default value. + +- `cache.project_expiry` (in seconds, default: 300) + +To stay operational, Relay regularly fetches project configurations from the Sentry upstream. This setting controls how often Relay fetches that configuration. You can decrease this value to make the configuration propagation more frequent. For example, if you later change data scrubbing options in your project settings in Sentry, your Relay instance will become aware of those changes faster. + +- `cache.project_grace_period` (in seconds, default: 0) + + How long a project configuration can still be used after having expired. + Increasing this value may help when the upstream is unreachable; for example, due to network issues. + +## Request Routing + +SDKs communicate with Sentry on a set of endpoints. Relay provides the same API to become a seamless drop-in replacement. This requires a set of endpoints to be accessible: + +- `/api//envelope/` +- `/api//minidump/` +- `/api//security/` +- `/api//store/` +- `/api//unreal/` + +Depending on the SDK or client, requests to these endpoints are performed with compressed content-encoding or chunked transfer-encoding. Depending on the infrastructure in front of Relay, please check the following HTTP headers are set correctly: + +- `Host`: to the public host name of this Relay +- `X-Forwarded-For`: to the client IP address +- `X-Sentry-Auth`: to the value provided by the client + + + +Proxies often set a default maximum body size for requests. Especially native crash reports and attachments can exceed these limits. We recommend to configure a maximum client body size of _100MB_. + + + +Internally, Relay makes requests to the configured upstream to forward data and retrieve project configuration. We **highly recommend against** constraining these requests. At present, Relay makes requests to the following endpoints for basic operation: + +- All of the above endpoints +- `/api/0/relays/projectconfigs/` +- `/api/0/relays/publickeys/` +- `/api/0/relays/register/challenge/` +- `/api/0/relays/register/response/` diff --git a/src/docs/product/relay/options.mdx b/src/docs/product/relay/options.mdx index 6e61716d7218b..2b05e8574c749 100644 --- a/src/docs/product/relay/options.mdx +++ b/src/docs/product/relay/options.mdx @@ -371,7 +371,8 @@ human-readable strings of a number and a human-readable unit, such as: : _String, optional_ - If set, reports the current hostname under the given tag name for all metrics. + 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. ## Internal Error Reporting