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 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.
Start by SSH’ing into your server and switching to the root user using
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
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:
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.
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
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:
To send events to Relay we need to update the DSN to look like this:
Note: We changed the protocol from
httpand the hostname from
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://[email protected]: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 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
comments powered by Disqus