---
title: Ruby custom metrics
source: https://docs.newrelic.com/docs/apm/agents/ruby-agent/api-guides/ruby-custom-metrics
---

Custom metrics let you record arbitrary performance data via an API call (for example, timing or computer resource data). Then use the [query builder](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder) to create charts and track that metric. You can use custom metrics to unify your monitoring inside New Relic.

> #### ⚠️ CAUTION
>
> Collecting too many metrics can impact the performance of your application and your New Relic agent. To avoid data problems, keep the total number of unique custom metrics under 2000.

## Naming metrics [#metric_names]

Metric names identify specific data values tracked by New Relic. When using the New Relic Ruby agent's API to track custom metrics, it's important to consider your metric naming and how the values will aggregate.

A custom metric name consists of the prefix `Custom/`, the class or category name, and a label, each separated with a slash mark `/`: `Custom/<class>/<method>` or `Custom/<category>/<name>` (for example, `Custom/MyClass/My_method`).

**Metric names and paths**

Metric names are paths delimited by a slash mark `/`. For custom instrumentation use this pattern:

````
<category>/<class>/<method>
```

To override the default metric name, pass a second argument to `add_method_tracer`. This may be necessary to specify a category other than the default `Custom`, or if the method and class name do not represent the metric well.

Reserved categories include:

* ActiveRecord
* Apdex
* CPU
* Controller
* Database
* Memory
* View
* Custom

<Callout variant="tip">
  For custom metric names, use `Custom/<class>/<method>` or `Custom/<category>/<name>`
</Callout>

````

**Metrics and stats in the Ruby agent**

There are two basic data structures used to collect metric data: `MetricSpec` and `Stats`.

A `MetricSpec` is an identifier for which we have data. The following pseudo Ruby defines a metric:

````rb
class MetricSpec
  attr_accessor :name    # String - metric name
  attr_accessor :scope   # String - current controller action
end
```

The name identifies what the metric represents. The optional scope is the name of the controller action handling the current request. A metric is "global" if the scope is empty.

Metric values are recorded by `Stats`. `Stats` typically collects data about method execution but can store any interesting data. The following pseudo Ruby defines `Stats`:

```rb
class Stats
  attr_accessor :call_count           # Integer - method invocation count
  attr_accessor :total_call_time      # Float - total method call time (in seconds)
  attr_accessor :total_exclusive_time # Float - total time spent in the traced method minus any child time (in seconds)
  attr_accessor :min_call_time        # Float - the smallest method invocation time (in seconds)
  attr_accessor :max_call_time        # Float - the largest method invocation time (in seconds)
  attr_accessor :sum_of_squares       # Float - the sum of squares of response times - used for standard deviation computation
  attr_accessor :begin_time           # Time - the start of the time window for this data
  attr_accessor :end_time             # Time - end of the time window for this data
end
```

````

**Stat aggregation policy**

One of New Relic's strengths is its ability to aggregate data over time. (Aggregation is the act of combining several things into one.) When collecting custom metrics, the aggregation policy can be important to know when collecting custom metrics. These include:

-   `call_count`: Addition
-   `total_call_time`: Addition
-   `total_exclusive_time`: Addition
-   `min_call_time`: Min() of each min_call_time
-   `max_call_time`: Max() of each max_call_time
-   `sum_of_squares`: Addition
-   `begin_time`: Min() of each begin_time
-   `end_time`: Max() of each end_time

## Record custom metrics [#recording-custom-metrics]

The public API for recording metric data consists of two methods on `NewRelic::Agent`, [`record_metric`](#record_metric) and [`increment_metric`](#increment_metric).

> #### 💡 TIP
>
> Both `record_metric` and `increment_metric` are thread safe.

### record_metric(metric_name, value) [#record_metric]

`record_metric` should be used to record an event-based metric, usually associated with a particular duration. `metric_name` must be a String following standard metric naming rules. `value` will usually be a Numeric, but may also be a Hash.

When `value` is a numeric value, it should represent the magnitude of a measurement associated with an event, such as the duration for a particular method call.

When `value` is a Hash, it must contain `:count`, `:total`, `:min`, `:max`, and `:sum_of_squares` keys, all with Numeric values. This form is useful if you wish to aggregate metrics on your own and report them periodically (for example, from a background thread). The provided stats will be aggregated with any previously collected values for the same metric. The names of the hash keys have been chosen to match the names of the keys used by the platform API.

### increment_metric(metric_name, amount=1) [#increment_metric]

`increment_metric` should be used to update a metric that acts as a simple counter. The count of the selected metric will be incremented by the specified amount.

## Example custom metric [#example]

Here is an example that shows how you might use metrics to track currency flowing through a site:

```rb
class Cart

  def checkout()
    amount = compute_cart_total    # computes the amount to charge the customer

    ::NewRelic::Agent.record_metric('Custom/Cart/charge_amount', amount)

    charge_customer(amount)
    ...
  end
end
```

For more information about how data aggregates over time, see [Stat aggregation policy](https://docs.newrelic.com/docs/ruby/ruby-custom-metric-naming#stat_policy).

## View custom metrics [#viewing-custom]

To view these custom metrics, use the [query builder](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder) to search metrics, create customizable charts, and add those charts to dashboards.