Oracle Cloud Infrastructure Documentation

Define Resource Dimension

After the APM Java agent is deployed, you can define the resource dimension in 2 different ways:

Simplified Resource Definition

The simplified resource dimension can be defined with key/value pair properties.

The key of property must be starting with com.oracle.apm.agent.resource.tag.

The following table shows different ways to define resource dimension in the simplified way:

Properties Type and Description Supported by Property Example

AgentConfig.properties

Update the AgentConfig.properties file located under oracle-apm-agent/config/<version> directory.

APM Agent com.oracle.apm.agent.resource.tag.<ResourceName> com.oracle.apm.agent.resource.tag.MyDepartment=Sales

System Properties

Update the system properties.

 APM Agent and APM Tracer com.oracle.apm.agent.resource.tag.<ResourceName>

-Dcom.oracle.apm.agent.resource.tag.MyDepartment=Sales

-Dcom.oracle.apm.agent.resource.tag.MyUser=${USERNAME}

-Dcom.oracle.apm.agent.resource.tag.MyAppVersion=${com.mycompany.myapp.version}

Environment Variables

Update the environment variables.

 APM Agent and APM Tracer com_oracle_apm_agent_resource.tag_<ResourceName>
For Windows: 
set com_oracle_apm_agent_resource_tag_MyDepartment=Sales
set com.oracle.apm.agent.resource.tag.MyUser=${USERNAME}
For Linux: 
export com_oracle_apm_agent_resource_tag_MyDepartment=Sales

Trace Builder

 APM Tracer com.oracle.apm.agent.resource.tag.<ResourceName> 
new ApmTracer.Builder(...)
    ...
    .withProperty("com.oracle.apm.agent.resource.tag.MyDepartment", "Sales")
    .withProperty("com.oracle.apm.agent.resource.tag.MyUser", "${USERNAME}")
    ...
    .build();

The value of the resource property can be a static text and/or a variable enclosed by ${ and } symbols.

One or more of the following is accepted as a resource dimension value:
  • Any text.
  • Key of the Java system properties enclosed by ${ and } symbols.
  • Key of the environment variables enclosed by ${ and } symbols. For example:
    ${USERNAME}

Comprehensive Resource Definition

Custom application server resource dimension can be defined to meet specific requirements.

To define a custom application server resource dimension, create a new configuration file named ResourceCollection.acml in the oracle-apm-agent/config/<version> directory.

The ResourceCollection.acml file is not created by APM Agent deployment and it must be created manually.

The format of ResourceCollection.acml is a custom ACML format (subset of YAML).

ACML Tag Data Type Required Description
RESOURCE:   yes Resource collection header.
<resource_entry_name>: string yes Reporting resource name.
property: <property key> string yes APM property key of the resource.

This is the property key of this resource value. It is also used by other resources for variable resolution.

type: <resource type> string yes Type of this property.
scalar: <resource scalar> string yes Resource value type.

Supported values are string, long, or double.
identity: <resource as identity> boolean No Flag indicates if this resource is used for appserver identity calculation.

Any resource with non-null value is used for appserverId dimension calculation.

priority: <collection priority> unsigned integer No Positive integer to indicate the resource collection priority. 0 (zero) is the highest priority. Custom resource should always set this value to 0 .
default: <default value> string No Default value of the resource when none of the specified sources returns a non-null value.
source: Not applicable yes Array node of the sources of this resource.

One or more child element can be defined for this source array. Each element is evaluated in order as defined, and the first one with non-null value is used.

If none of the element evaluation returned non-null value, then this resource is ignored.
- type: mbean string No Collect resource metadata from JMX mbean. Multiple can be defined for each resource.
mbean_name: <mbean object name> string No The mbean_name is the ObjectName of mbean.
value_path: <value selection path> string No

The value_path is the slash delimited selection path starting from specified mbean.

The first path node is the attribute of the mbean, then the value of the attribute is evaluated with each successive path node.

Evaluation supports the following

  • MBean attribute
  • ObjectName
  • Java object field name
  • java object no-arg method name
  • Key of CompositeData
  • Key of TubularData
  • Index of array
  • Key of Map
  • Index of Collection
<regex parsing> string No

The resource value selected can be further processed by using regex parsing tags. See Regex Parsing for more information.

type: property string No Resource value of system property or environment variable. Multiple can be defined for each resource.
key: <property key> string No The key name of system property or environment variable.
- type: value string No The static value. At most one should be defined in each resource because this value is never null.
value: <static value and/or variable> string No The value can be one or more of the following:
  • Fixed string.
  • System property.
  • Enviroment variable.
  • Resource property.

The properties keys contains the ${ and the } symbols which will be resolved at runtime into a value of specified key. If the specified property key is not found, the value of this resource will contain the unresolved key including the ${ and the } symbols.

<regex parsing> string No The resource value selected can be further processed by using regex parsing tags. See Regex Parsing for more information.

Regex Parsing

Regex parsing are additional tags of the source node to extract specific value of resource value with regular expression. For syntax details, see below:

Tag Base Type Description
regex: <regex:: string A regular expression against resource value with group construction.
<regex parsing> unsigned integer A group number of regex. The value of specified group is the final resource value.