Getting Started

Getting started with Relay is as simple as using the default settings. You can also configure Relay to suit your organization's needs. Check the Configuration Options page for a detailed discussion of operating scenarios.

Initializing Configuration

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.

# Adjust permissions for the configuration directory
# The :z option is only necessary on selinux.
# See https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label.
docker run --rm -it                  \
  -v $(pwd)/config/:/work/.relay/:z  \
  --entrypoint bash                  \
  getsentry/relay                    \
  -c 'chown -R relay:relay /work/.relay'

# Generate the configuration
docker run --rm -it                  \
  -v $(pwd)/config/:/work/.relay/:z  \
  getsentry/relay                    \
  config init

Select the default configuration to create a minimal configuration file. You can choose to override the default settings by selecting "create custom config" and customizing these parameters:

• The mode setting, which configures the major mode in which Relay operates. For more information on available Relay modes, refer to Relay Modes.

  Currently, only proxy and static mode are available to all organizations. Relay in managed mode is available only on the Business and Enterprise plans.

• The upstream setting configures the server to which Relay will forward the events (by default the main sentry.io URL).

• The port and host settings configure the TCP port at which Relay will listen. This is the address to which SDKs send events.

Settings are recorded in .relay/config.yml. Note that all configuration values are optional and default to these settings:

relay:
  mode: managed
  # 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://o0.ingest.sentry.io
  host: 0.0.0.0
  port: 3000

Configurations are fully documented in Configuration Options.

Creating Credentials

In addition to config.yml, the init command creates a credentials file, credentials.json, which is placed in the same .relay directory. This file contains both the public and private key Relay uses to authenticate with the upstream server.

As a result, this file must be protected from modification or view by unauthorized entities.

A typical credentials file is similar to this example:

{
  "secret_key": "5gkTAfwOrJ0lMy9aOAOmHKO1k6gd8ApYkAInmg5VfWk",
  "public_key": "nDJI79SbEYH9-8NEJAI7ezrgYfoIPW3Bnkg00k1z0fA",
  "id": "cde0d72e-0c4e-4550-a934-c1867d8a177c"
}

Use the public_key to register your Relay with the upstream server when running it in managed mode.

Registering Relay with Sentry

To operate in managed mode, Relay pulls configuration for PII stripping, filtering, and rate limiting from your organization and project settings in Sentry. Since these settings may contain sensitive information, their access is restricted by Sentry and requires authorization.

To register Relay with Sentry:

1. Copy the contents of the public key, either by inspecting the credentials.json file or by running:

   Run in DockerRun Executable

   Copied

   docker run --rm -it                \
     -v $(pwd)/config/:/work/.relay/  \
     getsentry/relay                  \
     credentials show
   

2. Click on Settings in the main navigation for Sentry, then select Relays.

3. Click New Relay Key to add the key and save it:

This process registers Relay with Sentry so it is ready to send messages. See Configuration Options to learn more about Relay configuration options.

Running Relay

After registering Relay with Sentry, it is ready to run:

docker run --rm -it                \
  -v $(pwd)/config/:/work/.relay/  \
  -p 3000:3000                     \
  getsentry/relay                  \
  run

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: 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 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:

docker run --rm -it                \
  -v $(pwd)/config/:/etc/relay/    \
  -p 3000:3000                     \
  getsentry/relay                  \
  run --config /etc/relay/

Sending 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 your project settings at Settings > Projects > {YOUR_PROJECT_NAME} > Client Keys (DSN), and select one of the existing DSNs, which looks similar to:

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

://12345abcdef10111213141516171819@

Use the new DSN in your SDK configuration. To test this, you can send a message with sentry-cli (installation instructions):

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.

Next Steps

• Learn more about our Operating Guidelines

With a working Relay instance, you can both monitor and scale your Relay setup.