Set Up Custom Instrumentation

Use Custom Instrumentation to add monitoring capabilities to technologies not supported by Oracle Application Performance Monitoring.

Why Use Custom Instrumentation?

• Technology used in application is not supported by Oracle Application Performance Monitoring.
• To obtain finer granularity of application performance metric breakdown.

Custom Instrumentation Guidelines

Custom Instrumentation is enabled by having the file custom-pointcuts.properties in Oracle Application Performance Monitoring Agent root config directory or appserver specific config directory.

For example, if the agent is provisioned to <weblogic_domain_home>, then custom-pointcuts.properties is automatically read from the location below:

<weblogic_domain_home>/apmagent/config/<appserver_name>/custom-pointcuts.properties

If the file name of custom pointcuts properties is other than custom-pointcuts.properties or it is placed in any directory other than appserver specific config directories, then add the following property to the JVM startup argument with the path to pointcuts file to enable custom instrumentation:

oracle.apmaas.agent.custom.pointcuts=<path_to_custom_pointcuts_file>

If Java system property is added to java executable argument, it is prefixed with -D. For example:

-Doracle.apmaas.agent.custom.pointcuts=<path_to_custom_pointcuts_file>

Note:

Log info on custom pointcut:

When agent found and read custom pointcuts properties file, a message gets printed to standard out:

"APMCS agent - INFO: Reading custom pointcut file [file=<path/to/custom/ pointcuts/properties/file>]"

Enable Method Invocation

To enable Method Invocation in Custom Instrumentation, follow these steps:

1. Open the AgentStartup.properties file:

   <weblogic_domain_home>/apmagent/config/<appserver_name>/AgentStartup.properties

2. Enable Method Invocation by editing the following line:

   oracle.apmaas.agent.probe.custom.enableMethodInvocation=true

Use the Thread Profiler

Use the thread profiler to identify key classes and methods you want to include in Custom Instrumentation.

Oracle Application Performance Monitoring includes a Thread Profiler to retrieve thread dump of JVM the APM Agent is running in. The steps below go over how to get the stack trace of an appserver monitored by Oracle Application Performance Monitoring.

If the classes and methods have already been identified, proceed to enable Custom Instrumentation. The full class and methods names will be needed.

1. In the Oracle Management Cloud menu, select Diagnostic Snapshots, then click Thread Profiles.
2. Click Start Thread Profiler.
3. Fill in the Name field and select and appserver for thread profiling. Click Start Profiler.
   The profiler will start in the pending state. Wait for the specified duration and refresh the page.
4. Click the profile name to show the Thread Profile Summary.
   The Thread Profile Summary includes the class and methods found from the profiling. The full class and method names will be needed to enable Custom Instrumentation.

Enable Custom Instrumentation

Enable Custom Instrumentation after the classes and methods that need to be monitored are identified.

1. Open a new terminal window in your host monitored by APM agent.
2. Navigate to the APM configuration files:

   $ cd /<agent_installation>/apmagent/config/<appserver_name>

3. Create a new file called: custom-pointcuts.properties
4. Add the following properties for each of the classes and methods to the file:
   • pointcut-<identity>.class=<class name>
   • pointcut-<identity>.method=<method name>

   Where: <identity> is an arbitrary unique name (same name for all properties of the same pointcut) to identify a pointcut.

   <class name> and <method name> are the full qualified class name and method name obtained from thread profiling.

   Repeat step 4 for each of the classes and methods to be monitored.

5. Save the file. Restart the appserver to enable custom instrumentation.

Example 4-1 custom-pointcuts.properties file

pointcut-scheduler.class=myapp.scheduler.MySchedule
pointcut-scheduler.method=startProcess

This example file adds a scheduler identity for class myapp and method startProcess.

Custom Instrumentation Reference

Syntax

Property Name	Required	Description	Example
pointcut-<identity>.class	YES	Full qualified class name to be instrumented. Only the specified class is instrumented. Sub class of the specified class can be done with name modifier (See Class Modifier). Also class name support willcard modifier (See Class Modifier).	myapp.HelloWorld myapp.HelloAll
pointcut-<identity>.method	YES	Name of method to be instrumented. Method name support modifier (See Method Modifier).	sayHello sayHi
pointcut-<identity>.paramTypes	NO	Comma separated full qualified class name of parameters of the method. If this property is not specified, all methods having the same specified method name of the specified class are instrumented. paramTypes property supports arbitrarily trailing classes (See ParaTypes Modifier)	java.lang.String javax.servlet.Servlet
pointcut-<identity>.operationName	NO	Name of operation. By default, instrumented server request name or operation name is generated by class name and method name. The default can be overridden by this property with a custom name.	Hello World

Section Modifier

Type	Modifier	Description	Example
wildcard	*	Character to match any character sequence of class name. If class name property is the wildcard character alone, Custom Instrumentation will instrument all classes which can cause significant performance impact.	pointcut-hello.class = myapp.* pointcut-hello.class = myapp.Hello*
subclass	+	Prefix class name with + to include subclasses of the specified class.	pointcut-hello.class = +myapp.HelloInterface

Method Modifier

Type	Modifier	Description	Examples
wildcard	*	Character to match any character sequence of method name. If method name property is the wildcard character alone, Custom Instrumentation will instrument all methods of specified class.	pointcut-hello.method = * pointcut-hello.method = say*

Parameter Type Modifier

Type	Modifier	Description	Examples
any trailing classes	...	To represent any number of trailing param classes.	pointcut-hello.paramTypes = ... pointcut-hello.paramTypes = java.lang.String, ... pointcut-hello.paramTypes = java.lang.String, int, ...

Operation Name Construction

Variable	Description
{class}	Simple name of Instrumented class.
{classFQN}	Full qualified name of instrumented class.
{method}	Instrumented method name.
{paramTypes}	Comma separated mehod parameters in simple class names.
{paramTypesFQN}	Comma separated mehod parameters in full qualified class names.

Example 4-2 Operation Name Construction

pointcut-hello.class = myapp.HelloWorld
pointcut-hello.method = sayHello
 
Here are some examples of operation name constructions:
pointcut-hello.operationName = Say Hello
pointcut-hello.operationName = Say Hello with Name
pointcut-hello.operationName = {class} {method} to everyone
pointcut-hello.operationName = {classFQN}.{method}
pointcut-hello.operationName = {classFQN}.{method}({paramTypes})

Sample:
pointcut-hello.class = myapp.HelloWorld
pointcut-hello.method = sayHello
  
pointcut-hi.class = myapp.HelloWorld
pointcut-hi.method = sayHi*
pointcut-hi.operationName = Say Hi
  
pointcut-hey.class = myapp.HeyWorld
pointcut-hey.method = sayHello
pointcut-hey.paramTypes = java.lang.String
pointcut-hey.operationName = Say Hello with Name
  
pointcut-helloAll.class = myapp.HelloWorld
pointcut-helloAll.method = sayHello
pointcut-helloAll.paramTypes = java.lang.String[]
pointcut-helloAll.operationName = {classFQN}.{method} to All

Avoid invalid custom pointcut configuration:

If the custom-pointcuts.properties file is not constructed as per the syntax given above or if the pointcut entries are not configured properly, then custom instrumentation will be ignored and there may not be any message printed to standard output, or logged in any log file.

Common invalid syntax in custom pointcuts properties:

• Mismatch unique pointcut name/id of an entry set
• Reuse of pointcut name/id between multiple entry set
• Typo in class and method names

Example 4-3 Invalid custom.pointcuts.properties files

pointcut-hello.class=myapp.HelloWorld

pointcut-hello1.method=sayHello  <== mismatch unique pointcut name

 
pointcut-hello.class=myapp.HelloWorld   <== reuse of 'hello' unique name as previous entry set.

pointcut-hello.method=sayHelloToAll  <== reuse of 'hello' unique name as previous entry set.


pointcut-helloyou.class = myapp.HelloWor   <==  typo in class name

pointcut-helloyou.method = sayHelloYou