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.

For valuePath configuration, it can mbean or mbeans.

For operationName configuration, it can be only mbean.

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.
operation_name string Name of the mbean method to be invoked. Note that the MBean must be registererd with Platform MBean Server.
params (Optional) string Values of method paramaters separated by comma.

The method parameters passed and their corresponding values will be captured as metric dimensions. Currently, only String datatype is supported for method paramaters.
Custom metrics can be defined in two ways using value_path or operationName attribute.
  • value_path attribute: Allows the metric to be extracted from the registered mbean
  • operationName attribute: Allows the user to register any custom class with the mbean server and invoke the mbean method, specified by the operationName.

Example using value_path attribute:

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).

Example using operationName attribute:

MyMetrics:
    CacheStatistics:
       type: measurement
       scalar: double
       skippable: false
       source:
        - type: mbean
          mbean_name:com.cache:type=CacheServiceMXBean
          operation_name: cacheStatistics
          params: SessionCache,JohnDoe
    DatabaseQueryTime:
       type: measurement
       scalar: long
       skippable: false    
       source:
        - type: mbean
          mbean_name: com.db:type=DbManagerMXBean
          operation_name: dbQueryTime

In the above example, metrics are collected at the top of every minute. There are two metrics to be collected: CacheStatistics and DatabaseQueryTime. Source for this mbean configuration can be mbean only.

For CacheStatistics, the mbean object name is com.cache:type=CacheServiceMXBean. The method to be invoked is cacheStatistics. The operation retrieves cache statistics for the specified cache name, filtered by its specific user. SessionCache and JohnDoe are the parameter values for CacheName and UserName respectively. User can construct a map of useful attributes such as AssociatedCacheName, CacheHits, CacheMisses, InMemoryHits, OnDiskHits as dimensions and return it as a part of supported return types as described below along with their corresponding values.

For DatabaseQueryTime, the mbean object name is com.db:type=DbManagerMXBean. The method to be invoked is dbQueryTime. No params have been configured for this mbean.

The supported method return types are:
  • Map<Map<String, Object>, Long>
  • Map<Map<String, Object>, Double>
  • Long
  • Double