In order to find out what specific pieces of code are causing performance problems it's useful to add custom instrumentation to your application. This allows us to create better breakdowns of which code runs slowest and what type of action was the most time spent on.
When you view saved samples of slow requests in AppSignal you'll be able to see all the instrumentation your application uses internally. Template rendering, ActiveRecord queries and caching are instrumented and will be shown in the sample.
That's already very useful, but wouldn't it be great if we could see measurements of specific pieces of code you suspect might influence your performance? Well, you can!
By adding custom instrumentation we can create more detailed breakdowns of a request and background job. There are two ways of instrumenting your code. With AppSignal instrumentation helpers or with ActiveSupport Notifications instrumentation, as is used by Rails.
Note: This page only describes how to add performance instrumentation to your code. To track errors please read our exception handling guide.
- AppSignal instrumentation helpers (Gem 1.3 and higher)
- ActiveSupport::Notifications instrumentation
This feature is available since AppSignal for Ruby gem 1.3. If you use an older version please use ActiveSupport::Notifications.
When you add custom instrumentation to your code you'll be able to receive even more insights into your application. For example, you have to work with an external API that fetches articles for your homepage:
1 2 3 4 5 6 7 8 9
class ArticleFetcher def self.fetch(category) Appsignal.instrument('fetch.article_fetcher') do # Download and process the articles end end end ArticleFetcher.fetch('Latest news')
Once you add custom instruments like this AppSignal will start picking them up
and will show you how much time both an event group (
article_fetcher in this
case) and individual events took.
In this case you'll notice that this API call is a huge influence on the performance of our homepage, which was hidden before. We might want to consider caching the articles.
Note: The name of the event you're instrumenting is important for our processor. Read more about event naming.
You can use as many instruments in any combination you like. You can nest instrument calls and AppSignal will handle the nesting and aggregates of the measurements nicely. You just have to keep the final segment (after the last dot) of the key consistent.
1 2 3 4 5 6 7
Appsignal.instrument('fetch.article_fetcher') do 10.times do Appsignal.instrument('fetch_single_article.article_fetcher') do # Fetch single article end end end
By default AppSignal will collect the duration of an event and send it to our servers. Since custom instrumentation is not hooked up to any framework internals you might need to pass along more data if you want event details to show up in AppSignal. This can be a descriptive title, or more specific information like the query from a database call. We already do this for ActiveRecord, Sequel, Redis, MongoDB, Sinatra, Grape, and more.
There are two helpers to allow you to instrument your code with AppSignal.
1 2 3
Appsignal.instrument(name, title = nil, body = nil, body_format = Appsignal::EventFormatter::DEFAULT, &block) # and Appsignal.instrument_sql(name, title = nil, body = nil, &block)
The name of the event that will appear in the event tree in AppSignal. Read more about event key naming.
A more descriptive title of an event, such as
"Fetch current user" or
blog post comments". It will appear next to the event name in the event tree
on the performance sample page to provide a little more context on what's
1 2 3
Appsignal.instrument('fetch.custom_database', 'Fetch current user') do # ... end
More details such as a database query that was used by the event.
1 2 3 4
sql = 'SELECT * FROM posts ORDER BY created_at DESC LIMIT 1' Appsignal.instrument('fetch.custom_database', 'Fetch latest post', sql) do # ... end
Warning: Please make sure the body payloads are sanitized (sensitive/dynamic data is removed). Non-sanitized body events will be discarded if they reach a certain limit.
1 2 3 4 5 6
Appsignal.instrument('custom.instrument', 'Instrument stuff', 'command/dynamic/?') do # ... end Appsignal.instrument('custom.instrument', 'Instrument stuff', 'command/dynamic/?') do # ... end
1 2 3 4 5 6
Appsignal.instrument('custom.instrument', 'Instrument stuff', 'command/dynamic/123') do # ... end Appsignal.instrument('custom.instrument', 'Instrument stuff', 'command/dynamic/234') do # ... end
When passing in an SQL query as the body, you can use
Appsignal::EventFormatter::SQL_BODY_FORMAT to do so.
Body format supports formatters to scrub the given data in the
to remove any sensitive data from the value. There are currently two supported
values for the
Appsignal::EventFormatter::DEFAULT is the default value of this
argument. By default AppSignal will leave the value intact and not scrub any
data from it.
Appsignal::EventFormatter::SQL_BODY_FORMAT value will run your data
through the SQL sanitizer and scrub any values in SQL queries.
We recommend you use the
Appsignal.instrument_sql helper for this instead.
1 2 3
SELECT * FROM users WHERE email = 'email@example.com' AND password = 'iamabot' -- becomes SELECT * FROM users WHERE email = ? AND password = ?
In older versions of the AppSignal gem (1.2 and lower) the
Appsignal.instrument is not available. If you cannot upgrade, it's still
possible to use
If you don't want to use the
Appsignal.instrument helper, but instead want to
ActiveSupport::Notifications, you can still do so in AppSignal for Ruby
gem 1.3 and higher too.
The method for instrumenting your code using
is very similar to how AppSignal does it. Using the article fetcher example
again you can see the differences are quite small.
Also see our documentation on AppSignal event formatters when using
For more information about ActiveSupport::Notifications instrumentation, see the official Rails
1 2 3 4 5 6 7 8 9 10 11
require "active_support" class ArticleFetcher def self.fetch(category) ActiveSupport::Notifications.instrument("fetch.article_fetcher") do # Download and process the articles end end end ArticleFetcher.fetch("Latest news")
It works for nested instrumentation calls as well.
1 2 3 4 5 6 7 8 9
require "active_support" ActiveSupport::Notifications.instrument("fetch.article_fetcher") do 10.times do ActiveSupport::Notifications.instrument("fetch_single_article.article_fetcher") do # Fetch single article end end end
ActiveSupport::Notifications is highly flexible, you can instrument your code
any way you like. More information about
ActiveSupport::Notifications can be
found in the
Rails API docs.
Warning: We do not track private
that start with an exclamation mark (
!). These events mostly include
private events generated by Rails.