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.
The Relay server is called relay
. Download binaries from GitHub Releases. A Docker image is provided on DockerHub.
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.
In Docker, provide the configuration directory using the standard mechanisms offered by Docker, either by mounting Docker volumes or by building a new container and copying in the files.
# 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
andstatic
mode are available to all organizations. Relay inmanaged
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 mainsentry.io
URL).The
port
andhost
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.
Not applicable in proxy
or static
mode.
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.
Not applicable in proxy
or static
mode.
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:
Copy the contents of the public key, either by inspecting the
credentials.json
file or by running:Copieddocker run --rm -it \ -v $(pwd)/config/:/work/.relay/ \ getsentry/relay \ credentials show
Click on Settings in the main navigation for Sentry, then select Relays.
- 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.
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/
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:
://12345abcdef10111213141516171819@ /2345http
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.
With a working Relay instance, you can both monitor and scale your Relay setup.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").