Setup Sentry Relay on Ubuntu

Sentry offers Relay, it's a proxy or relay that sits between your application and Sentry and can be used to filter events, add additional information, and more. In it's simplest form it can be used to relay events to Sentry (which is why it's called that 😉).

There are a few key benefits to me that make Relay a great addition to your Sentry setup:

• Speed: Since you can deploy Relay close to your application (usually on the same host), you can send events to Sentry almost instantly without much networking overhead

• Reliability: Relay will queue events when the Sentry instance is unreachable and tries to send them when Sentry is reachable again but while Sentry is down your application can continue to send events to Relay without any issues

Especially for PHP applications Relay is a must-have since PHP is single threaded so every ms spent waiting for Sentry to respond is a ms your application can't do anything else and when Sentry is down or slow your application could be slow as well. The PHP SDK (of which I am a maintainer) tries to do as much as it can to minimize the impact of sending events to Sentry but it can only do so much and Relay solves the problem. See also Improve Response Time from the PHP/Laravel/Symfony docs.

There are 3 operating modes for Relay:

• managed (only available on Business and Enterprise plans or self-hosted): Relay will request project settings from Sentry, so it can be configured from the UI.

• static: Relay is configured with specific DSNs it will allow, and allow accepts events for those projects.

• proxy: Relay will proxy requests to Sentry, and will forward any event you sent to it.

I will focus on the proxy mode in this guide since it's the easiest to setup but apart from the specific configuration the setup is the same for all modes.

If you'd rather follow the official guide, you can find it here, I will focus on running a binary with systemd but there is also a Docker option in the official Getting Started guide.

Installing Relay

Start by SSH'ing into your server and switching to the root user using sudo su.

Now the fun begins, starting with downloading the latest Relay binary from the Sentry Relay releases page.

You want to download the relay-Linux-x86_64 release asset since that is the binary for Linux, at the time of writing there is no ARM binary.

1wget -O sentry-relay https://github.com/getsentry/relay/releases/download/23.8.0/relay-Linux-x86_64

Next we want to make the binary executable by setting the appropriate permissions:

1chmod +x sentry-relay

Now we can move the binary to /usr/local/bin so it's available globally:

1mv sentry-relay /usr/local/bin

Configuring Relay

We downloaded the binary and made it available globally, now we need to configure Relay so it knows how to connect to Sentry and what to do with the events it receives.

Start by creating a folder the configuration file, and use sentry-relay to generate the config.yml. This YAML file contains the configuration for Relay and if you need to edit it later you can find it at: /etc/sentry-relay/config.yml.

1mkdir -p /etc/sentry-relay
2sentry-relay config init -c /etc/sentry-relay

This will ask a few questions on how to setup Relay, you can find the answers below:

 1Q: Do you want to create a new config?
 2A: Yes, create custom config
 3
 4Q: How should this relay operate?
 5A: Proxy for all events
 6
 7Q: upstream
 8A: https://sentry.io/
 9
10Q: listen interface
11A: 127.0.0.1
12
13Q: listen port
14A: 3000
15
16Q: do you want listen to TLS
17A: no

Setup systemd service

We downloaded the binary, made it executable, and created a configuration file. We are almost done!

Now we need to setup systemd so Relay will start on boot and can be managed via systemd.

We first need to create a user for Relay to run as, this is a security measure so Relay can't access any files it shouldn't be able to access.

1useradd -r -s /bin/false sentry-relay

This new user needs to be the owner of the configuration file we created earlier:

1chown -Rf sentry-relay:sentry-relay /etc/sentry-relay

We also need to create a systemd service file for Relay, this will tell systemd how to start Relay and what user to run it as.

 1cat << EOF > /etc/systemd/system/sentry-relay.service
 2[Unit]
 3Description=Sentry Relay
 4After=network.target
 5StartLimitIntervalSec=0
 6 
 7[Service]
 8Type=simple
 9Restart=always
10RestartSec=3
11User=sentry-relay
12ExecStart=/usr/local/bin/sentry-relay run --config /etc/sentry-relay
13 
14[Install]
15WantedBy=multi-user.target
16EOF

After creating the systemd service file we need to reload systemd so it knows about the new service file and then enable the service so it will start on boot.

1systemctl daemon-reload
2systemctl enable sentry-relay

Now we can start the service:

1systemctl start sentry-relay

And check the status:

1systemctl status sentry-relay

Sending events to Relay

The last part is updating the DSN in your application to send events to Relay instead of Sentry directly.

Your DSN looks something like this:

https://12345abcdef10111213141516171819@o1.ingest.sentry.io/2345

To send events to Relay we need to update the DSN to look like this:

http://12345abcdef10111213141516171819@127.0.0.1:3000/2345

Now that Relay is running and we have our updated DSN we can send events to it, let's use sentry-cli to do that (installation instructions):

1export SENTRY_DSN='http://12345abcdef10111213141516171819@127.0.0.1:3000/2345'
2sentry-cli send-event -m 'A test event using Relay'

If everything went well you should see a new event in your Sentry project!

Updating Relay

Updating Relay is as simple as downloading the latest binary and replacing the old one, you can do this with the following commands:

 1# Download the latest binary (replace the version with the latest one)
 2wget -O sentry-relay https://github.com/getsentry/relay/releases/download/23.8.0/relay-Linux-x86_64
 3 
 4# Make the binary executable
 5chmod +x sentry-relay
 6 
 7# Move the binary to /usr/local/bin
 8mv sentry-relay /usr/local/bin
 9 
10# Restart the Sentry Relay service
11systemctl restart sentry-relay