Modify Probe Settings
You can modify or disable default probe settings, or enable a custom probe to monitor additional classes.
The following probe tasks are covered in this topic:
Modify or Disable Default Probe Settings
You can modify or disable the default probe settings using the
ProbeConfig.acml
file.
After you provision an APM Java agent, the ProbeConfig.acml
file is available under the oracle-apm-agent/config
directory. For information on how to access the ProbeConfig.acml
file, see Provision the APM Java Agent.
The ProbeConfig.acml
file allows you to do the
following:
- Enable or disable particular probes.
- Disable monitoring of specific patterns of traces/spans based on information such as URL, file extension, etc.
- Enable capturing of additional tags/dimensions. For example, capturing specific headers and parameters for SERVLET probe.
- Manipulate the span name. For example, manipulating the URL for SERVLET or HTTP_CLIENT probes.
- Capture DB sql query statements with more than 1,000 characters in
length as a span log.
To enable or disable logging of the entire sql query statements in jdbc span log, use the
enable_complete_sql_span_log_jdbc
parameter. This feature is helpful when having a long sql query truncated at 1,000 characters. For example, use :enable_complete_sql_span_log_jdbc: true
to enable it. - Capture the logged in username.
Hashed usernames are captured for the authenticated sessions with the intention to allow reporting on number of unique users, without exposing personal identifiable information (PII). However, there may be a need to report username in plain text format. In that case, go to the general section and set
track_plain_username: true
.
The default behavior can be updated using ProbeConfig.acml
file from the APM Java agent.
To make changes to the default probe settings, follow the instructions available in the ProbeConfig.acml
file.
Changes to the ProbeConfig.acml
file can be made when the application server is running and the application server does not have to be restarted for the changes to take effect.
Starting with APM Java agent version 1.12 , there's an improved and simplified operation of naming convention for Servlet, HttpClient and OSB probes. Therefore, the replace_all_patterns
rule for removing Hex ID and numbers is no longer included by default in the ProbeConfig.acml
file. This applies to the SERVLET, HTTP_CLIENT and OSB sections.
# Hex ID and numbers
-
pattern: "([a-fA-F\._\:-]*[0-9]+){2,}[a-fA-F_\:-]*([/\.])?"
replacement: "*$2"
Configure a Custom Probe
You can configure a custom probe to monitor additional classes and obtain application-specific details.
The custom probe is useful if the built-in set of probes available in the
ProbeConfig.acml
file do not meet monitoring requirements. For
example, if you want to monitor a background thread that is not monitored using the
default probes, then you can configure a custom probe to monitor it.
To configure a custom probe, do the following:
- Configure a
DirectivesConfig.acml
file to specify whichclasses
,methods
, orannotations
should be monitored. For more information, see DirectivesConfig.acml File Configuration. - Add the
DirectivesConfig.acml
file tooracle-apm-agent/config
directory.It is now deprecated to specify theRemove the above argument from your application's startup script if you have previously specified theDirectivesConfig.acml
file using the following in the startup script of your application server:-Dcom.oracle.apm.agent.customDirectivesFile=<Path_to_DirectivesConfig.acml_file>
DirectivesConfig.acml
file this way. - Restart the application server if a new
DirectivesConfig.acml
file is specified.The changes to the
DirectivesConfig.acml
file takes effect after you restart the application server.The application server restart is required when specifying a new
DirectivesConfig.acml
file or deleting the file.The application server restart is not required if doing any of the following:- Edit the
span_name
. - Add, edit or delete
tags
,logs
or Advanced Variables in an existingDirectivesConfig.acml
file that is already in effect.
- Edit the
DirectivesConfig.acml File Configuration
To configure the DirectivesConfig.acml
file, review the
following:
DirectivesConfig.acml Parameters
Here's information on the parameters you can specify in the
DirectivesConfig.acml
file.
At least one of the following parameters MUST be specified in the
DirectivesConfig.acml
file:
class_name
class_name_regex
class_annotation
method_annotation
class_annotation_regex
method_annotation_regex
Parameter | Description | Example |
---|---|---|
label |
A unique label for the directive. This is a mandatory parameter. |
|
class_name |
The name of the class you want to monitor. You must specify the full class name, including the package. |
|
class_name_regex |
A regular expression (regex) pattern to monitor any class that matches it. For the regex pattern, instead of using "." for the
package, use "/". For example, if you want to monitor a class
called If both |
|
method_name |
The name of the method you want to monitor. This does not include method parameters. If |
|
method_name_regex |
A regex pattern to monitor any method that matches it. If If both |
|
class_annotation |
The full class name of the annotation you want to
monitor. Any |
|
method_annotation |
The full class name of the annotation you want to
monitor. Any |
|
class_annotation_regex |
A regex pattern to monitor any class annotation that matches it. For the regex pattern, instead of using "." for the
package, use "/". Also, the value should begin with "L" and end
with ";". For example, if you want to monitor an annotation
called If both |
|
method_annotation_regex |
A regex pattern to monitor any method annotation that matches it. For the regex pattern, instead of using "." for the
package, use "/". Also, the value should begin with "L" and end
with ";". For example, if you want to monitor an annotation
called If both |
|
include_sub_classes |
Specify if subclasses of the target class must be
monitored. By default, this is set to
|
|
span_name |
The name of the span created during monitoring. If
the Note that you can specify a name for the span, as
shown under the When specifying the |
|
tags |
The tags (names and values) to be included in the span. As in the case of the Note that the For tag values, an optional type can be specified. You can specify the tag value to be of type String, Boolean, Integer, Long, Float, or Double by using the appropriate syntax and keyword (as shown in the example). The default tag value type will be String. This will be used if no type or an incompatible type is specified. If an incompatible type is specified for a tag value, the type will revert to the default of String, and there will be a log message about the incompatibility. The span dimension value can be confirmed through queries with aggregations that leverage numeric values (if applicable) in the Trace Explorer. |
|
logs |
The logs (names and values) you want to be included in the span. As in the case of the Note that the |
|
span_name, tags and logs Variables
When specifying the span_name
, tags
and
logs
parameters, the following variables can be used to
acquire additional information:
class_name
: Name of the class being monitored, including the package.short_class_name
: Name of the class being monitored, excluding the package.method_name
: Name of the method being monitored.method_descriptor
: Descriptor format of the method's signature being monitored.param#
: Parameters of the method being monitored, in whichparam1
denotes the first parameter,param2
the second parameter, and so on.this
: Object being monitored. Note that if themethod
being monitored isstatic
, thenthis
variable will not be available.return
: Return value of the method being monitored.Note
Thereturn
variable can only be used for thetags
parameter and not forspan_name
.
DirectivesConfig.acml Example
Here's an example of the DirectivesConfig.acml
file:
Test:
class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
method_name: "performHttpURLConnectionCall"
include_sub_classes: true
span_name: "${short_class_name}.${method_name}"
tags:
targetURL: "${param2}"
port: "${param1}"
Based on the above example:
com.oracle.apm.samples.servlet.OutboundTestServlet.performHttpURLConnectionCall
will be monitored, along with its subclasses.- The name of the span displayed in Trace Explorer will be
OutboundTestServlet.performHttpURLConnectionCall
. - The
targetURL
andport
tags will be added to the span, and will use the values of the first and second parameters of theperformHttpURLConnectionCall
method.
The following screenshots are an example of the custom probe page:
Advanced Variables for Custom Probing
When using custom probe, you can configure advanced command syntax to
dynamically construct variables using method chaining and string manipulation via
regular expressions. These advanced variables can be referenced in the
span_name
, tags
, and logs
sections, just like the other variables mentioned above.
- Review how to configure custom probe. See Configure a Custom Probe.
- Review the command chain syntax. See Command Chain Syntax.
- Review the examples. See Advanced Variables Examples.
Command Chain Syntax
The pipe symbol "|" is used to signify piping the starting object to the first chain command and piping output object of one chain command to the next.
Execution Time
The command chains are executed before or after the monitored method of the Custom Probe is invoked. This is specified by the execution time, which appears before the SOI.
<execution time> ::= [before || after]
Not all Command Chains are compatible with both execution times: When
return
is used as an SOI or as a parameter in a method command,
the after execution time must be used. This is because the return object is only
available after the monitored method is invoked. When other variables are used as
SOIs or parameters in method commands, execution times are dependent on the
referenced chains.
For example, let's define chain1
and chain2
, where
chain2
uses chain1
as an SOI or parameter for
a method command. Note that chain1
must be defined before
chain2
if both chains use the same execution time. Otherwise,
chain1
must have execution time before, and
chain2
must have execution time after.
More information about using SOIs and the method commands can be found in the below section Starting Object Identifier.
Starting Object Identifier
A Starting Object Identifier (SOI) can be objects associated with:
-
Predefined keywords:
this
,return
andparam#
. -
Output of a chain identified by its key.
Execution times can be paired with SOI syntax.
SOI | Description | Possible Execution Time | Syntax | Example |
---|---|---|---|---|
ThisSOI | The chain is executed on the object specified by
class_name in the DirectivesConfig.acml
file.
|
before or
after |
<this SOI> ::= [before || after]
this |
thisSOIchain: before this | method
(public getAddress ()) |
ParamSOI | The chain is executed on the object specified by param# in the DirectivesConfig.acml file.
These are parameters of the method being monitored. |
before or after |
<param_SOI> ::= [before || after] param# |
paramSOIchain: before param1 | method (public getAddress ())
|
ReturnSOI | The chain is executed on the object specified by
return in the DirectivesConfig.acml file.
This is the return value of the method being monitored. |
after |
<return_SOI> ::= [after]
return |
returnSOIchain: after return | method
(public getAddress ()) |
StaticSOI | The chain is not started with any object. | before or after |
<static SOI> ::= [before || after]
static |
staticSOIchain: before static | static method((com.test.beans.Employee)(public getLevel())) |
VariableSOI | The chain is executed on the object specified by one of the above variables defined in the DirectivesConfig.acml file. | before or after |
<variable_SOI> ::= [before ||
after] variable-key |
var1: this | method (public setNewAddress
(string "Variable Street", string "Redwood City", string
"California", int 94065, string
"US"))
|
Chain Command Sequence
A chain command sequence consists of one or more chain commands.
Syntax:
<chain_command_sequence> ::= <chain_command> ||
<chain_command> | <chain_command_sequence>
Chain Command Types
Syntax:
<chain_command> ::= <method_command> || <field_command> ||
<regex_command>
Method Command
A method command is used to invoke a method. The output of a method command is the return object of that specific method.
A method command consists of method visibility, method name, and parameter sequence. This mimics the method signature.
The syntax should look like the following:
<method_command> ::= method(<visibility> <java_identifier>
(<parameter_sequence>))
<visibility> ::= private || public || protected || package
The package
value is used to specify a package-private (no-modifier)
visibility method or field.
<scalar_parameter_type> ::= int || double || float || String
<parameter> ::=<scalar_parameter_type> value || this || return ||
param<index> || variable-key
<parameter_sequence> ::= <parameter> || <parameter> ,
<parameter_sequence>
Method Command Examples
-
This chain shows
this
as User object. This chain invokes the publicgetAddress
method in the User class. The output of this chain will be the string representation of this User's address.addresschain: this | method (public getAddress ())
-
This chain invokes the
public setName
method on the User, and sets the name to "John Smith". Since this set method has no return value, the output of this chain will be null. This chain demonstrates how to use scalar parameters in method commands.testSetupVar: this | method(public setName(String "John", String "Smith"))
-
This chain uses
param1
(the first parameter of the method being monitored) as a parameter for the method we are invoking.testParamAsParam: this | method(public incUserId(param1))
-
This chain uses another variable, in this case
testParamAsParam
, as a parameter for the method.testVarAsParam: this | method(public incUserId(testParamAsParam))
-
This chain invokes super method explicitly.
invokeUsingSuper: this | method(private super.overloadPrivate(String "string3", int 2222))
Field Command
A field command is used to inspect field values. The output of a field command is the object in that specific field.
A method command consists of field visibility and field name.
Syntax:
<field_command> ::= field (<visibility>
<java_identifier>)
Field Command Examples
this
is a user Object.
Here we are accessing fields of various visibility in the User class. The output of
each chain is the value of the respective field.
fieldPublic: this | field(public firstName)
fieldProtected: this | field (protected lastName)
fieldPackagePrivate: this | field (package middleName)
fieldPrivate: this | field (private maidenName)
Static Method Command
A static method command is used to invoke a static method. The output of a static method command is the return object of that specific method.
A method command consists of a starting class, method visibility, method name, and parameter sequence. This mimics the method signature.
<static_method_command> ::= static method((<starting_class>)(<visibility> <java_identifier> (<parameter_sequence>)))
The starting class is the class in which the static method is found.
- This chain starts with no object. This chain invokes the public
getlevel
method in the Employee class. The output of this chain will be the string representation of this Employee's level. staticMethodPublic: static | static method((com.test.beans.Employee)(public getLevel()))
- Use of other visibilities and different types of method parameters are the same as in the examples for Method Command.
Static Field Command
A static field command is used to inspect static field values. The output of a static field command is the object in that specific field.
A method command consists of a starting class, field visibility, and field name.
Syntax:
<static_field_command> ::= static field ((<starting_class>)(<visibility> <java_identifier>))
Static Field Command Examples:
The below example assumes that this
is a user Object. Here we are accessing fields of various visibility in the User class. The output of each chain is the value of the respective field.
staticFieldPublic: static field((com.test.beans.Employee)(public role))
Use of other visibilities is the same as in the examples for Field Command.
Regex command
A regex command is used to find and/or replace strings resulting from the SOI, return values of the method commands, or the field values. The output of a regex command is a string.
A regex command consists of the regex string. Optionally it can also consist of a replacement string, along with whether first or all occurrences should be replaced.
Syntax: <regex_command> ::=regex (string [,<replace-string> [, first || all]])
Regex Command Examples
- After getting address "100 Oracle Pkway, Redwood City, CA 94065," replace the first "Pk" with "This" to get "100 Oracle Thatway, Redwood City, CA 94065
replaceFirstChain : this | method (public getStreet()) | regex(Pk, This, first)
- After getting address "100 Oracle Pkway, Redwood City, CA 94065," replace all "0"s with "1" to get "111 Oracle Pkway, Redwood City, CA 94165"
replaceAllChain: this | method (public getStreet()) | regex(0, 1, all)
Advanced Variables Examples
Here's an example of a command chain in the DirectivesConfig.acml
file.
test: class_name: "com.test.beans.User"
method_name: "incAge"
span_name: "${short_class_name}.${method_name}"
tags:
t: "${this}"
params: "${param1}"
r: "${return}"
exampleVarTag: "${exampleVar}"
variables:
exampleVar: before this | method (public getAddress ()) | field(private street) | regex(Pk,This, all) | regex(This, That, first)
Review of the exampleVar
Variable Chain
Execution:
exampleVar
chain starts with the User object which
is specified in "class_name".XX
-
The first chain command is a method command which returns an Address object. For example: "100 Oracle Pkway, Redwood City, CA 94065."
-
The second chain command is a field command that gets the street of the address from the previous field command. This will be "Oracle Pkway."
-
The third chain command is a regex command that replaces all instances of "Pk" with "This" and returns "Oracle Thisway."
-
The last chain command is a regex command that replaces the first instance of "This" with "That," returning "OracleThatway."
Final Result: When looking at Dimensions of this span, you see a
tag called exampleVarTag with the value "OracleThatway". Note that specifying
exampleVarTag: "${exampleVar}"
in the tags section was
necessary to see this span dimension.