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.

Note: I am assuming a few things in this guide. That the reader knows how to use SSH and can perform basic command line actions. It is also assumed you are installing Relay on a Ubuntu server with systemd (the guide was tested on Ubuntu 18.04/20.04/22.04).

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.

If you are using Ploi to manage your servers you can use this marketplace script that performs the steps outlined below. However I highly recommend you read through this guide so you know what is happening and how to update Relay in the future.

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.

Note: At the time of writing the latest release is 23.8.0, but you should check the release page to see if there is a newer version.

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.

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

chmod +x sentry-relay

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

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

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

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

Q: Do you want to create a new config?
A: Yes, create custom config

Q: How should this relay operate?
A: Proxy for all events

Q: upstream
A: https://sentry.io/

Q: listen interface
A: 127.0.0.1

Q: listen port
A: 3000

Q: do you want listen to TLS
A: no

Note: If you run a self-hosted instance replace the upstream answer with the hostname of your self-hosted instance.

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.

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

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

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

cat << EOF > /etc/systemd/system/sentry-relay.service
[Unit]
Description=Sentry Relay
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=3
User=sentry-relay
ExecStart=/usr/local/bin/sentry-relay run --config /etc/sentry-relay

[Install]
WantedBy=multi-user.target
EOF

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.

systemctl daemon-reload
systemctl enable sentry-relay

Now we can start the service:

systemctl start sentry-relay

And check the status:

systemctl 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

Note: We changed the protocol from https to http and the hostname from o1.ingest.sentry.io to localhost:3000. If you used different listen interface or port when creating the configuration make sure to re-use those here!

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

export SENTRY_DSN='http://12345abcdef10111213141516171819@127.0.0.1:3000/2345'
sentry-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:

# Download the latest binary (replace the version with the latest one)
wget -O sentry-relay https://github.com/getsentry/relay/releases/download/23.8.0/relay-Linux-x86_64

# Make the binary executable
chmod +x sentry-relay

# Move the binary to /usr/local/bin
mv sentry-relay /usr/local/bin

# Restart the Sentry Relay service
systemctl restart sentry-relay