How to use custom metrics

Robert Beekman

Robert Beekman on

How to use custom metrics

Deeper insights with custom metrics

With the AppSignal gem you could already use custom instrumentation to get more details about your application performance. But sometimes you want to track other metrics as well.

With the 1.0 release of our gem, you can send custom metrics to AppSignal. These metrics enable you to track anything in your application, from new accounts to database disk usage. These are not replacements for code instrumentation, but an additional way to make certain data in your code more accessible and measureable over time.

We offer three types of metrics:

GaugeA number you can overwrite useful to store things like user count.
CounterA number that can be incremented by the given value, useful to count the times a process runs for example.
DistributionA collection of numbers for wich we store the average and the count. Useful to track average sale amount.

The AppSignal gem has a methods for each of these metrics types. You can use these methods to send data to our systems.


The gauge is ideal for metrics that can both increase and decrease. We use the gauge in AppSignal to graph the number of active accounts.

count =
Appsignal.set_gauge('account_count', count)


As the name suggests, counters are a great way to keep track of how many times something happens. Our workers process a payload that contains multiple data points. This means the count of the job doesn't accurately represent the amount of data we process. With the counter we increment for each data point we process.

minute.metrics.each do |metric|
  Appsignal.increment_counter('metric_count', metric.length)


We use distributions to measure the average time a piece of code takes to execute. For example a job can run multiple map/reduce jobs and even though we track the duration with instrumentation, we still want to see the average duration for each job in a nice graph.


Turning metrics into graphs

Sending metrics to AppSignal is only half of the story, after sending data we need to create graphs to show the metrics. We do this in the editor on the "custom metrics" page.

Custom metrics editor

Our custom metrics feature allows you to create multiple screens with graphs. You can define the screens and the graphs on these screens through a YAML format.

For example to create a screen with account releaed graphs, showing a graph with the number of accounts you can use the following YAML:

- title: Account overview
    - title: "Number of accounts"
      kind: gauge
      format: number
        - account_count

This wil result in the following page:

Custom metrics editor

Instead of a list with fields you can also provide a regex that matches one or more metric names. The example below renders a graph with lines for each API response code for a 3rd party API.

- title: API Responses
    - title: "API response codes"
      kind: count
      filter: "api_response_code_[0-9]+"
      format: number

These are just a few of many useful metrics you can now track with AppSignal. For more information about custom metrics, check our documentation or contact us if you need any help setting this up for your account.

Write for our blog

Would you like to contribute to the AppSignal blog? We're looking for skilled mid/senior-level Ruby, Elixir, and Node.js writers.

Find out more and apply

Share this article

Robert Beekman

Robert Beekman

As a co-founder, Robert wrote our very first commit. He's also our support role-model and knows all about the tiny details in code. Travels and photographs (at the same time).

All articles by Robert Beekman

AppSignal monitors your apps

AppSignal provides insights for Ruby, Rails, Elixir, Phoenix, Node.js, Express and many other frameworks and libraries. We are located in beautiful Amsterdam. We love stroopwafels. If you do too, let us know. We might send you some!

Discover AppSignal
AppSignal monitors your apps