Install AppSignal for Rails

Follow Chris Oliver as he installs and configures AppSignal in a Rails application.

Presented by Chris Oliver for GoRails. Republished on AppSignal September 25, 2026.

You have worked on your app idea for months. You deploy to production, and test signup and the other features to make sure everything works. Then you put your product out there. People start signing up, which is great. But then messages from customers start popping up in your mailbox with complaints:

• Pages are loading really slowly.
• When I try to reset my password, the email to complete the process never arrives.
• Is the app broken?

That is when you notice that you lack visibility into production, and realize you need to sign up for AppSignal.

Chris installs the appsignal gem in a Ruby on Rails application deployed on Hatchbox. He configures it by hand so you can see what each option does. Then he deploys it, and uses AppSignal to find an error his users hit.

Want an AI coding agent to handle the setup? Follow Set up a new application with AI.

What this covers

• Adding the AppSignal for Ruby gem and running the install command.
• Choosing which environments report to AppSignal.
• Keeping your Push API key out of your repository with Rails encrypted credentials.
• Ignoring noisy actions and namespaces, and reporting a revision with each deploy.
• Confirming data arrives, then investigating the first real error your users hit.

Requirements

What	Value
Framework	Ruby on Rails
Gem	appsignal
Account	An AppSignal account, for its Push API key

Install AppSignal

After signing up, choose the framework or language your app uses. In this walkthrough, that is a Ruby on Rails app deployed on Hatchbox. The AppSignal AI setup flow can also identify it from your app’s environment and run the installation. Or go old school, as this walkthrough does, and install everything manually from AppSignal’s UI flow:

1. First, you must select Add app and then choose Ruby & Rails.

2. Add the AppSignal for Ruby integration gem to your Gemfile like so:

   # Gemfile
   source "https://rubygems.org"
   gem "appsignal"
   

3. Run bundle install to download and install the AppSignal Ruby gem for you.

4. Finally, configure it with your organization’s Push API key.

   bundle exec appsignal install <YOUR_PUSH_API_KEY>
   

The install command verifies your Push API key. It then asks whether you want a friendlier name for your app, and which configuration file to use. This walkthrough declines the rename and picks the Ruby configuration file, so config.name keeps the name the installer detected. The wizard then sends an example error to AppSignal. It checks your installation by waiting for that error to arrive.

For the latest detailed commands and requirements, also read the documentation on Installing AppSignal for Ruby.

Using the Ruby configuration file

The install command writes your answers to config/appsignal.rb. Because the configuration is a Ruby file, every change you make is saved in your Git repository. That helps if you ever want to change things later or undo them.

By default, AppSignal only activates in the development and production environments.

Usually, development environments are used to test and break things. You might replace the default "development" environment with "staging", for example. Then you can catch errors and fix them before they go to production.

# Visit our documentation for a list of all available configuration options.
# https://docs.appsignal.com/ruby/configuration/options.html
   Appsignal.configure do |config|
      config.activate_if_environment("staging", "production")

      config.name = "AppsignalExample"

Storing credentials safely

Run rails credentials:edit to open your editor, paste your AppSignal Push API key, and save it as a secret. Next, copy the contents of config/master.key to your clipboard. On macOS, run cat config/master.key | pbcopy. Then go to your hosting environment, for instance Hatchbox, and set it as the RAILS_MASTER_KEY environment variable.

# smtp:
#   user_name: my-smtp-user
#   password: my-smtp-password
#
# aws:
#   access_key_id: 123
#   secret_access_key: 345

# Used as the base secret for all MessageVerifiers in Rails, including
# the one protecting cookies.
secret_key_base: <YOUR_SECRET_KEY_BASE>

appsignal:
  api_key: "<YOUR_PUSH_API_KEY>"

  # Your application's Push API key
  # We recommend removing this line and setting this option with the
  # APPSIGNAL_PUSH_API_KEY environment variable instead
  # This will use Rails' encrypted credentials so you can manage them safely in your repository
  # https://docs.appsignal.com/ruby/configuration/options.html#option-push_api_key
      config.push_api_key = Rails.application.credentials.dig(:appsignal, :api_key)

Ignoring actions, namespaces, and configuring a revision file

New Rails applications have a default route called /up, which you can see in config/routes.rb. It is built into Rails, and returns a 200 or 500 status to show whether your application is running. This is useful for uptime and health checks by your load balancer to verify your app is live. Your load balancer hits this route every few seconds. You do not always need this route, or other very busy routes, to report back to AppSignal.

Alternatively, let AppSignal collect data and monitor your app over the next 24 hours. See what it reports, and fine-tune it later on.

  # Configure actions that should not be monitored by AppSignal.
  # For more information see our docs:
  # https://docs.appsignal.com/ruby/configuration/ignore-actions.html
      config.ignore_actions << "Rails::HealthController#show"

Ignore any metrics and Action Cable messages related to an action_cable namespace. This might be useful because WebSockets in Rails Action Cable probably generate a considerable amount of noise. Let’s say your Hatchbox application is sending real-time events and log messages constantly to browsers. This might burn through your AppSignal quota if this namespace is on.

Finally, your Hatchbox deployment writes a revision file that contains your Git commit SHA. config.revision reads that file, so AppSignal links all metrics, errors, logs, and anything else reported to that deploy.

Use this file to track the errors that you fix and deploy changes for. If they come back after your deployment, AppSignal lets you know that those errors are not really fixed.

  # Configure errors that should not be recorded by AppSignal.
  # For more information see our docs:
  # https://docs.appsignal.com/ruby/configuration/ignore-errors.html
      config.ignore_errors << "MyCustomError"

      config.ignore_namespaces << "action_cable"

      config.revision = File.read("REVISION")
end

Here’s the complete file from our walkthrough.

# Visit our documentation for a list of all available configuration options.
# https://docs.appsignal.com/ruby/configuration/options.html
   Appsignal.configure do |config|
      config.activate_if_environment("staging", "production")

      config.name = "AppsignalExample"

  # Your application's Push API key
  # We recommend removing this line and setting this option with the
  # APPSIGNAL_PUSH_API_KEY environment variable instead
  # This will use Rails' encrypted credentials so you can manage them safely in your repository
  # https://docs.appsignal.com/ruby/configuration/options.html#option-push_api_key
      config.push_api_key = Rails.application.credentials.dig(:appsignal, :api_key)

  # Configure actions that should not be monitored by AppSignal.
  # For more information see our docs:
  # https://docs.appsignal.com/ruby/configuration/ignore-actions.html
      config.ignore_actions << "Rails::HealthController#show"

  # Configure errors that should not be recorded by AppSignal.
  # For more information see our docs:
  # https://docs.appsignal.com/ruby/configuration/ignore-errors.html
      config.ignore_errors << "MyCustomError"

      config.ignore_namespaces << "action_cable"
      config.revision = File.read("REVISION")
end

Commit the configuration and push it to your repository:

git add .
git commit -m "Add appsignal"
git push

Deploy your app

After saving to your Git repository, hop over to your deployment and server management platform, like Hatchbox. Make sure your Rails master key value matches config/master.key, then deploy your app. You should see a production environment added to AppSignal. It appears next to your development environment and the demo error you sent while installing. After your deployment is ready, AppSignal will show your app’s metrics and requests on the dashboards. Switch to the production environment to watch requests come through.

Find the error your users reported

You can then try to replicate the error your users got, such as the password reset email that never arrived:

1. Head over to your dashboards and check the Error rate (%) chart. AppSignal separates web requests from background jobs, such as Solid Queue, into their own namespaces.

2. Select the Errors > Issue list and open the error you want to investigate further. It will show the error message and backtrace, for example “Make sure your API key is set”.

3. In Hatchbox, set the missing Resend API key in your Environment Variables, and save it. That gets rid of the error your users got.

   In this walkthrough, the missing key belongs to Resend, the service the app sends email through. Create an API key in Resend with sending access for all domains, then set it in Hatchbox. Until you verify a domain, a Resend test account only delivers to its own test address. Send the password reset to [e-mail], and confirm the email arrives in your Resend dashboard.

4. Head back to AppSignal Errors > Issue list and in your error Settings, mark its status as “Closed”.

AppSignal dashboards also show a marker for each deployment and revision you make. You can see the errors between deployments. Throughput will indicate if things got slow after the deployment of a new feature. There is a lot more you can do and investigate in your app with AppSignal. Intelligence dashboards are also generated automatically for the Rails features AppSignal detects. In this walkthrough, it detected Active Job sending emails, and generated dashboards for Action Mailer and Active Job. Each has its own dashboard, showing what is happening in that part of your Rails application. To dive deeper into your framework and language of choice, read the AppSignal for Ruby documentation. It covers how AppSignal integrates with your application and gives you visibility into it.

Transcript

Transcribed from the video and lightly edited. The automatic captions misheard several product and API names, and those have been corrected.

Read the transcript

0:00 Picture this, you’ve been working on your product idea for months, and it’s finally ready. You deployed to production, you sign up, you test everything out, it looks like it’s working great. So you go ahead and send it to your friends, your family, your email newsletter, your social media accounts, trying to get users, and people start signing up, which is good.

0:18 Until you get messages from people saying, “Hey, this page loads really slowly,” or things like, “Hey, I tried to reset my password,” and the email just never arrived. “Is it broken? Like, what’s going on?” And you realize, “I have no visibility into production at all. What do I do?” Well, you sign up for AppSignal.

0:39 So today we’re going to be installing AppSignal on our procrastinate app here, and we’re going to dive in by signing up, of course, for AppSignal and then installing it in our app. Now, as you go do this, you can choose to follow the framework or language of choice that you’re using for us, it’s Ruby on Rails, but I would recommend just using their AI prompt for it.

1:00 So they’ve got docs and a prompt and everything ready to go, so you can just copy-paste this, drop it into Claude Code or Codex or whatever you are using, and it will do the installation stuff for you. It can also, of course, configure things as well, so you can ask it to fine-tune things, but we’re going to do it the hard, old-school way manually, so you can see exactly what it’s doing behind the scenes.

1:24 So all we need to do is add the library, so bundle add appsignal is going to download and install the AppSignal Ruby gem so we can use it, and then, of course, we need to configure it to use our API key. And that’s what this install command is going to do, so it’s going to verify our API key, ask us if we want to have a friendlier name for our app, we’ll say no, and then how we want to configure it.

1:47 We’ll use the Ruby configuration file, so everything we do, we’ll get saved in our Git repository, which is going to be handy later when we change this, maybe we want to undo some things or whatever, and this is going to send over an example error. So let’s continue on with this wizard, and you’ll learn a little bit more about how AppSignal works, but then it’s going to check the installation, it’s looking for that example error that came across in our install.

2:13 So while it’s doing that, let’s open up config/appsignal.rb and take a look at what its default configuration is. So first, it’s going to only activate if it’s in one of these environments that are pre-configured, so development and production. Of course, we’re in development on our local machine, but in production on a server, we’ll have the production environment.

2:36 Now, I don’t particularly care about tracking errors in development, because I’m often breaking things as I build features, and it’s going to send metrics and errors and everything over to AppSignal, and I don’t need those, I’m not really going to look at them. So I’m going to remove that, and I might replace that with staging, for example, and that will allow my staging environment to report errors and everything, so I want to catch those and fix them before they get to production, for example.

3:03 Then you can, of course, also rename it in here as well, and your Push API key is going to be what allows you to send data to AppSignal. Now, this we want to actually remove, we don’t want it to be hard-coded, so we’re going to say Rails.application.credentials.dig(:appsignal, :api_key). What this is going to do is use Rails’ encrypted credentials, so we can store that secret in the encrypted credentials in our Git repository, nice and safely.

3:35 So we’ll go over to our other tab here and say rails credentials:edit, and this will open up our editor, drop to the bottom and add the matching keys, AppSignal API key, and paste in that secret. So we’ll save that, and then all we have to do is take the output of config/master.key, and I’m on a Mac so I can use pbcopy to copy it on the clipboard, and then you want to go into your hosting environment.

4:07 For us, we’re using Hatchbox, and you’ll set RAILS_MASTER_KEY as an environment variable to that value. So go ahead and do that, I’ve already set mine up so I don’t need to, but we will continue back in the AppSignal config here.

4:23 There’s a few other things you might want to consider when you’re setting up your AppSignal config. One of those is that you will probably want to do something like the health controller, show action, being ignored. So what this does, and let’s open up our routes file so you can see exactly that.

4:44 In new Rails application, since Kamal came out, you now have a default route called /up, and this goes to a controller that’s built into Rails that just says, “Hey, your Rails application is running.” This is useful for uptime checks or health checks by your load balancer or whatever, and so this route, it doesn’t really do anything, but it is useful. So it’s important, and it will get hit often, especially if it’s in a load balancer, where it’s doing active health checks.

5:13 Just hitting this route every a few seconds saying, “Are you still alive? Are you still alive?” Yes, I’m still alive, but we don’t need any of that data to actually be reported back to AppSignal, so I like to ignore that. So other routes that might be very busy that you want to ignore, you could add here, I would say leave it alone and see what happens in production, see what data AppSignal collects over the next four hours or 24 hours, whatever it is, and then you can go fine-tune things later on.

5:44 And of course you can use AI to analyze that and then fine-tune things accordingly. Same with ignoring errors, I wouldn’t add anything to this list normally unless I really knew that something specific. We wanted to ignore because obviously we want to track errors and fix them, so we want to collect as much as possible, especially for something like errors.

6:06 One thing we may not want to collect is if we do ignore namespaces, we can say any Action Cable messages and metrics related to that, we want to ignore, so everything in that namespace in AppSignal will be ignored. And this is important because if you’re using WebSockets in Rails Action Cable, the framework for that, it’s going to generate probably a very lot of noise.

6:33 So in our application Hatchbox, we’re sending real-time events and log messages constantly to the browser, and so when we install AppSignal and don’t have this on, we just burn through our quota really quickly. So you would probably want to leave this out for your initial install and then come back and add stuff like this later after an hour or two or whatever a day. Once you’ve had time to see what actually are we reporting, what is really busy if we’re burning through our quota and our AppSignal plan, then we can fine-tune it.

7:09 All right, last but not least, I want to mention the config.revision. So the way that Hatchbox deploys, we create a revision file that shows or contains the Git commit SHA that you have deployed. So there’s many ways to access this. Every hosting provider is a little bit different. Some are using environment variables, we do too. But you can also customize this to say like file read, the revision file, and have that be written as the deploy that all of those metrics or errors or anything else reported back to AppSignal are related to.

7:45 This is very useful because if you fix an error and you deploy a change that was supposed to fix that error, the error ever comes back up after that deploy. AppSignal can then notify you and say, “Hey, you didn’t really fix that. You thought you did, but we saw it again.” And maybe it’s a different edge case or something, but it helps you keep track of those.

8:04 So once you get notified about an error, if it happens a hundred times, you’re not going to get a hundred notifications. But if you deploy and it comes back, then they’re going to notify you again. So you’re aware that, “Hey, that wasn’t actually fixed.” And that’s very, very helpful to know.

8:20 So those are some of the default customizations I like to do. So we’re going to git add all of these changes, and we’re going to say git commit -m "Add appsignal". And we’ll push that up to our Git repository, and we can hop over to our application on Hatchbox and deploy those changes.

8:40 Now, in your environment, remember, I mentioned you want to have your Rails master key set, and we just want to check and make sure that this value exactly matches what was on our clipboard here with config/master.key, and that is the exact same thing. So once this deployment has finished and is successful, we’ll be able to reload our application, it’ll restart automatically, of course, but then we should see a production environment being added to AppSignal.

9:12 So let’s take a look at what it’s created so far. We have a development environment for AppsignalExample, the application we’re doing, and we’ve got an error that it reported here. And if we take a look at the errors list, we see an Appsignal::Demo::TestError. This, of course, is the test error that the install command sent over. That’s what it was looking for while it was checking the installation, and it found it so it was good to go.

9:40 So that’s excellent. Our deployment is now successful. So let’s refresh the page and see if there’s any metrics being sent over to AppSignal. So I have the development environment, but now we should see a production environment up here, and we can switch to that and we should see that requests are now coming through. I’ve made three requests per minute, for example, here, which is a good sign that we have everything wired up correctly.

10:05 Now let’s try and replicate that error and see if it comes through as well. We’ll go to forgot your password, put in our email address, and send that. No 500 error, nothing like that. So maybe there’s something happening in the background, and then we can take a look at AppSignal and see if it caught anything that we didn’t get us the visually as a user.

10:24 And now we can see an error did come through, and we have one error in the background namespace. So it’s automatically split out our Rails server from the background jobs, in our case, Solid Queue. And so it separated those out, and you can see them here in different colors as well. Since this happened in the background, it is a blue line, and so we can go over to the errors list as well and dig into exactly what was wrong.

10:50 We are using Resend for emails, and it looks like we got a Resend error. So let’s click on that and take a look at what was the error message. Make sure your API key is set. Oh, totally forgot to put that in there. So for us, we can go over to Resend, create an API key, and we will have an AppSignal.

11:11 Example is the name. We’ll give it full access or sending access for all domains, and then we’ll copy this over and put this in our environment. So I know that this is supposed to be a Resend API key, paste that in, save changes, and we should now be good to go, and we should be able to send this email out and have it run successfully.

11:35 So now let’s try this out again, and I remembered that I need to use a special email address for Resend for testing without having a valid domain yet, because I’m just in their test account. So we’re going to send an email to [e-mail]. And in their dashboard, we should now see reset your password has arrived just now. I just created that account so we could test with it, but we can confirm that now our background jobs are working and not sending errors anymore, and they’re actually using my real Resend API key.

12:07 So this error can be considered resolved, we can go over and close it ourselves, but we can also see when we do another deployment that this will have another dot down here, which will collect each deployment that we make the time and the Git revision as well. So we’ll be able to see those over time and see the errors in between each one of those deployments, and we can also see the throughput as well so you can see that maybe things got a lot more slow after deployment of a certain feature.

12:38 Maybe we needed to fix some performance thing or whatever. Of course, this is just the tip of the iceberg, AppSignal has a lot more you can do with it. And for example, refreshing the page, we can already see their new dashboards for Action Mailer and Active Job that have been generated automatically for us because it detected that we were using Active Job to send out emails.

12:56 So both of those features of Rails have their own special dashboards that you can see and get information about exactly what’s happening with those parts of your Rails applications. So take a look at the docs to dive in deeper for your framework and your language of choice and see how AppSignal can better integrate and give you visibility into your applications.

Related tutorials

• Run background jobs with Solid Queue
• Inspect background jobs with Mission Control

About this tutorial

This tutorial follows, step by step, a GoRails screencast on installing AppSignal in a Rails application deployed on Hatchbox, by Chris Oliver. The screencast is the original work. GoRails publishes it, and the rest of the series, at gorails.com.