Oracle Cloud Infrastructure Documentation

Collect Metrics

APM Java agent supports collecting application server metrics periodically.

After the APM Java agent is deployed, you can collect the following types of metrics:

Default Metrics

Default metrics are system-defined metrics that are available by default.

For a complete set of default metrics, see Available Metrics: oracle_apm_monitoring for APM Java Agent.

Custom Metrics

Custom metrics are user-defined metrics that can be created in addition to the existing default metrics to meet specific requirements.

To define a custom metric, create a new configuration file named MetricCollection.acml in the oracle-apm-agent/config/<version> directory.

The MetricCollection.acml file is a custom file in ACML format (subset of YAML) for custom metric collection configuration.

ACML Tag Data Type Description
<group name>: string Group to separate metrics with different collection start_time and interval.
<metric name>: string Name of metric to be collected. One metric name corresponds to only one value. Naming convention is a string in lower case separated by dash.
type: string Type of metric. It can measurement or delta.

- measurement: current runtime value.

- delta: value different between collection interval.
scalar: string Type of numeric value: It can long or double.
source:   Tag representing array of source entries of metric. Each metric may contain one or more source entries. Even if there are more than one source entry, each entry is check at collection in order. Whenever the entry can return valid value, it is used for the metric entry, and the rest of source entries are ignored.
-   Metric source entry array element.
type: string Type of metric source. It can mbean or mbeans.
mbean_name: string MBean object name for mbean or mbeans type. For mbeans type, object name can have wildcard character ( * ), but wildcar is not supported for mbean.
value_path: string Path is separated by slash ( / ) to get the value of mbean. The value path must lead to a numeric value. Besides the root path that must be the attribute name of mbean object, split path can be one of the following of previous path value:
  • Object field name.
  • Method name of object that take no parameter.
  • Key of CompositeData.
  • Key of TubularData.
  • Index of array.
  • Key of Map.
  • Index of Collection.

For mbeans type, the value of each mbean object are aggregated. Similarly, if wildcard character ( * ) is used in path for mbeans type, all values retrieved are aggregated.

For example: 


MyMetrics:
    jvm-used-heap:
        type: measurement
        scalar: long
        source:
          -
            type: mbean
            mbean_name: java.lang:type=Memory
            value_path: HeapMemoryUsage/used
    jvm-used-heap-after-old-gc:
        type: measurement
        scalar: long
        source:
          -
            type: mbeans
            mbean_name: java.lang:type=GarbageCollector,name=*Old*
            value_path: LastGcInfo/memoryUsageAfterGc/*/value/used
          -
            type: mbeans
            mbean_name: java.lang:type=GarbageCollector,name=*MarkSweep*
            value_path: LastGcInfo/memoryUsageAfterGc/*/value/used

In the above example, metrics are collected at the top of every minute. There are two metrics to be collected: jvm-heap-used and jvm-used-heap-after-old-gc.

For jvm-heap-used, there is only 1 source which is mbean. The mbean object name is java.lang:type=Memory. This mbean object has an attribute of HeapMemoryUsage which has data type of CompositeDataSupport. It is not numeric and cannot be used as metric. However, it represents a map of metrics that we used heap can be retrieved from, therefore the drill down to the object with used map key is needed.

For jvm-used-heap-after-old-gc, it has 2 sources: mbeans, both are in plural with an 's'. Metric is collected in the order per definition and the first source returning a valid metric is used. The reason of having 2 sources is because different java versions have different garbage collector names. The value_path drill down also used wildcard, and all used memory after gc values of all memory spaces are summed up as a single metric value. The data drill down of the value path is LastGcInfo/memoryUsageAfterGc/*/value/used which refers to: LastGcInfo(CompositeData)/memoryUsageAfterGc(TabularData)/<index>(CompositeData)/value(MemoryUsage)/used(Long).