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
-
Open the AgentStartup.properties file:
<weblogic_domain_home>/apmagent/config/<appserver_name>/AgentStartup.properties
- 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.
Enable Custom Instrumentation
Enable Custom Instrumentation after the classes and methods that need to be monitored are identified.
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). |
|
pointcut-<identity>.method | YES | Name of method to be instrumented. Method name support modifier (See Method Modifier). |
|
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) |
|
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. |
|
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. |
|
subclass | + | Prefix class name with + to include subclasses of the specified class. |
|
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. |
|
Parameter Type Modifier
Type | Modifier | Description | Examples |
---|---|---|---|
any trailing classes | ... | To represent any number of trailing param classes. | pointcut-hello.paramTypes = ...
|
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