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

  • The upstream setting configures the server to which Relay will forward the events (by default the main 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:

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

projectRepresents your service in Sentry and allows you to scope events to a distinct application.
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:

    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.

add relay key

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

edit relay key

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                  \

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

DSNThe Data Source Name (DSN) key tells the Sentry SDK where to send events, ensuring they go to the right project.
of your
projectRepresents your service in Sentry and allows you to scope events to a distinct application.
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:

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:


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@'
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

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

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
Suggest an edit to this page   |  Contribute to Docs   |  

Report a Problem

🎉 Thank you for your feedback! 🙌
Report a problem