ifdef::env-github[]
NOTE: For the best reading experience,
please view this documentation at https://www.elastic.co/guide/en/apm/agent/ruby[elastic.co]
endif::[]

[[metrics]]
== Metrics

The Ruby agent tracks various system and application metrics.
These metrics will be sent regularly to the APM Server and from there to Elasticsearch.
You can adjust the interval by setting <<config-metrics-interval,`metrics_interval`>>.

The metrics will be stored in the `apm-*` index and have the `processor.event` property set to `metric`.

[float]
[[metrics-system]]
=== System metrics

**Note:** Metrics from the Ruby agent are Linux only for now.

[float]
[[metric-system.cpu.total.norm.pct]]
==== `system.cpu.total.norm.pct`

* *Type:* Float
* *Format:* Percent

The percentage of CPU time in states other than Idle and IOWait,
normalised by the number of cores.

[float]
[[metric-system.memory.total]]
==== `system.memory.total`

* *Type:* Long
* *Format:* Bytes

The total memory of the system in bytes.

[float]
[[metric-system.memory.actual.free]]
==== `system.memory.actual.free`

* *Type:* Long
* *Format:* Bytes

Free memory of the system in bytes.

[float]
[[metric-system.process.cpu.total.norm.pct]]
==== `system.process.cpu.total.norm.pct`

* *Type:* Float
* *Format:* Percent

The percentage of CPU time spent by the process since the last event.
This value is normalized by the number of CPU cores and it ranges from 0 to 100%.

[float]
[[metric-system.process.memory.size]]
==== `system.process.memory.size`

* *Type:* Long
* *Format:* Bytes

The total virtual memory the process has.

[float]
[[metric-system.process.memory.rss.bytes]]
==== `system.process.memory.rss.bytes`

* *Type:* Long
* *Format:* Bytes

The Resident Set Size,
the amount of memory the process occupies in main memory (RAM).

[float]
[[metrics-ruby]]
=== Ruby Metrics

[float]
[[metric-ruby.gc.counts]]
==== `ruby.gc.count`

* *Type:* Integer
* *Format:* Count

The number of Garbage Collection runs since the process started.

[float]
[[metric-ruby.threads]]
==== `ruby.threads`

* *Type:* Integer
* *Format:* Count

The number of threads belonging to the current process.

[float]
[[metric-ruby.heap.slots.live]]
==== `ruby.heap.slots.live`

* *Type:* Integer
* *Format:* Slots

Current amount of heap slots that are live.

**NB:** Not currently supported on JRuby.

[float]
[[metric-ruby.heap.slots.free]]
==== `ruby.heap.slots.free`

* *Type:* Integer
* *Format:* Slots

Current amount of heap slots that are free.

**NB:** Not currently supported on JRuby.

[float]
[[metrics-ruby.heap.allocations.total]]
==== `ruby.heap.allocations.total`

* *Type:* Integer
* *Format:* Objects

Current amount of allocated objects on the heap.

**NB:** Not currently supported on JRuby.

[float]
[[metrics-ruby.gc.time]]
==== `ruby.gc.time`

* *Type:* Float
* *Format:* Seconds

The total time spent in garbage collection.

**NB:** You need to enable Ruby's GC Profiler for this to get reported.
You can do this at any time when your application boots by calling `GC::Profiler.enable`.

[float]
[[metrics-jvm-metrics]]
=== JVM Metrics

The following metrics are available when using JRuby. They use the ruby java API to gather metrics via MXBean.

[float]
[[metric-jvm.memory.heap.used]]
==== `jvm.memory.heap.used`

* *Type:* Long
* *Format:* Bytes

The amount of used heap memory in bytes.

[float]
[[metric-jvm.memory.heap.committed]]
==== `jvm.memory.heap.committed`

* *Type:* Long
* *Format:* Bytes

The amount of heap memory in bytes that is committed for the Java virtual machine to use. This amount of memory is
guaranteed for the Java virtual machine to use.

[float]
[[metric-jvm.memory.heap.max]]
==== `jvm.memory.heap.max`

* *Type:* Long
* *Format:* Bytes

The amount of heap memory in bytes that is committed for the Java virtual machine to use. This amount of memory is
guaranteed for the Java virtual machine to use.

[float]
[[metric-jvm.memory.non_heap.used]]
==== `jvm.memory.non_heap.used`

* *Type:* Long
* *Format:* Bytes

The amount of used non-heap memory in bytes.

[float]
[[metric-jvm.memory.non_heap.committed]]
==== `jvm.memory.non_heap.committed`

* *Type:* Long
* *Format:* Bytes

The amount of non-heap memory in bytes that is committed for the Java virtual machine to use. This amount of memory is
guaranteed for the Java virtual machine to use.

[float]
[[metric-jvm.memory.non_heap.max]]
==== `jvm.memory.non_heap.max`

* *Type:* Long
* *Format:* Bytes

The maximum amount of non-heap memory in bytes that can be used for memory management. If the maximum memory size is
undefined, the value is -1.

[float]
[[metric-jvm.memory.heap.pool.used]]
==== `jvm.memory.heap.pool.used`

* *Type:* Long
* *Format:* Bytes

The amount of used memory in bytes of the memory pool.

[float]
[[metric-jvm.memory.heap.pool.committed]]
==== `jvm.memory.heap.pool.committed`

* *Type:* Long
* *Format:* Bytes

The amount of memory in bytes that is committed for the memory pool. This amount of memory is guaranteed for this
specific pool.

[float]
[[metric-jvm.memory.heap.pool.max]]
==== `jvm.memory.heap.pool.max`

* *Type:* Long
* *Format:* Bytes

The maximum amount of memory in bytes that can be used for the memory pool.