Modify Probe Settings

You can modify or disable default probe settings, or enable a custom probe to monitor additional classes.

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.

Note

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.

If your specific scenario still requires it, add the following back in the file after upgrading the APM Java agent:
# 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:

  1. Configure a DirectivesConfig.acml file to specify which classes, methods, or annotations should be monitored. For more information, see DirectivesConfig.acml File Configuration.
  2. Add the DirectivesConfig.acml file to oracle-apm-agent/config directory.
    It is now deprecated to specify the DirectivesConfig.acml file using the following in the startup script of your application server:
    -Dcom.oracle.apm.agent.customDirectivesFile=<Path_to_DirectivesConfig.acml_file>
    Remove the above argument from your application's startup script if you have previously specified the DirectivesConfig.acml file this way.
  3. 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 existing DirectivesConfig.acml file that is already in effect.
    The application server restart is required if changing any other parameters from the table below under DirectivesConfig.acml Parameters.

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.

Test:
  ...
Test2:
  ...
Test3:
  ...
class_name

The name of the class you want to monitor. You must specify the full class name, including the package.

Test:  
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
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 a.b.c.d.ClassName, then the regex pattern should match against a/b/c/d/ClassName.

If both class_name_regex and class_name are specified, then class_name is ignored.

Test:
  # Monitor all classes under the com.oracle.apm.test package
  class_name_regex: "com/oracle/apm/test/.*"
method_name

The name of the method you want to monitor. This does not include method parameters.

If method_name is not specified, then all methods are monitored.

Test:
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
  method_name "performHttpURLConnectionCall"
method_name_regex

A regex pattern to monitor any method that matches it.

If method_name_regex is not specified, then all methods are monitored.

If both method_name_regex and method_name are specified, then method_name is ignored.

Test:
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
  # Monitor all methods that start with "perform"
  method_name_regex: "perform.*"
class_annotation

The full class name of the annotation you want to monitor. Any class with the specified annotation is monitored.

Test:
  class_annotation: "javax.jws.WebService"
method_annotation

The full class name of the annotation you want to monitor. Any method with the specified annotation is monitored.

Test:
  method_annotation: "javax.jws.WebMethod"
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 a.b.c.d.Annotation, then the regex pattern should match against La/b/c/d/Annotation;.

If both class_annotation_regex and class_annotation are specified, then class_annotation is ignored.

Test:
  # Monitor all Path annotations in javax
  class_annotation_regex: "Ljavax/.*/Path;"
Test2:
  # Monitor all annotations that end with "Path"
  # The L in the beginning is not required since .* includes it
  class_annotation_regex: ".*/Path;"
Test3:
  # Monitor all annotations with the javax.jws package
  # The ; at the end is not required since .* includes it
  class_annotation_regex: "Ljavax/jws/.*"
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 a.b.c.d.Annotation, then the regex pattern should match against La/b/c/d/Annotation;.

If both method_annotation_regex and method_annotation are specified, then method_annotation is ignored.

Test:
  # Monitor all Path annotations in javax
  method_annotation_regex: "Ljavax/.*/Path;"
Test2:
  # Monitor all annotations that end with "Path"
  # The L in the beginning is not required since .* includes it
  method_annotation_regex: ".*/Path;"
Test3:
  # Monitor all annotations with the javax.jws package
  # The ; at the end is not required since .* includes it
  method_annotation_regex: "Ljavax/jws/.*"
include_sub_classes

Specify if subclasses of the target class must be monitored. By default, this is set to false.

Test:
  class_name: "com.oracle.apm.samples.servlet.OutboundTestServlet"
  method_name "performHttpURLConnectionCall"
  include_sub_classes: true
span_name

The name of the span created during monitoring. If the span_name is not specified, "${class_name}.${method_name}" is used by default.

Note that you can specify a name for the span, as shown under the Test label in the corresponding example, which will then be used every time the monitored target is invoked.

When specifying the span_name parameter, you can also use variables, ${variable_name} and Advanced Variables, to acquire additional information regarding the parameters you're monitoring and display them in the name of the span. In the corresponding example, under the Test2 label, the param# variable denotes the parameters aligned with the method you're monitoring.

Test:
  ...
  # The same name will be used every time the target class/method is invoked
  span_name: "SpecialName"
Test2:
  ...
  # Use the toString result of the first parameter passed to the monitored method
  span_name: "${param1}"
tags

The tags (names and values) to be included in the span.

As in the case of the span_name parameter, you can use variables when specifying values for tags to acquire and display additional information regarding the parameters you're monitoring.

Note that the tags you specify are displayed as Dimensions in the Trace Explorer user interface.

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.

Test:
  ...
  tags:
    importantInfo: "${param1}"
    consistentTag: "AlwaysTheSame"
    returnValue: "${return}"
    #The below tag will have value of default type String since no type was specified
    defaultTagType: "${param1}"
    #The below tag will have value of type Integer
    integerTag: "${param1} | integer"
    #The below tag will have value of type String, because the actual value type String, and the specified type Double are incompatible. Therefore it will default to String.
    booleanTag: "${param2} | double"
logs

The logs (names and values) you want to be included in the span.

As in the case of the span_name and tags parameters, you can also use variables when specifying values for the logs parameter to acquire and display additional information regarding the parameters you are monitoring.

Note that the logs you specify are displayed as Span Logs in the Trace Explorer user interface.

Test:
  ...
  logs:
    importantInfoLog: "${param1}"
    consistentLog: "AlwaysTheSame"
    returnValueLog: "${return}"
  ...

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 which param1 denotes the first parameter, param2 the second parameter, and so on.
  • this: Object being monitored. Note that if the method being monitored is static, then this variable will not be available.
  • return: Return value of the method being monitored.
    Note

    The return variable can only be used for the tags parameter and not for span_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 and port tags will be added to the span, and will use the values of the first and second parameters of the performHttpURLConnectionCall method.

The following screenshots are an example of the custom probe page:

Custom Probe Example Screenshot 1

Custom Probe Example Screenshot 2

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.

General Workflow for Using Advanced Variables
  1. Review how to configure custom probe. See Configure a Custom Probe.
  2. Review the command chain syntax. See Command Chain Syntax.
  3. Review the examples. See Advanced Variables Examples.

Command Chain Syntax

A command chain consists of the following three parts:

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 and param#.

  • 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 ())

param1 denotes the first parameter.

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

var1UsedAsStartObject: after var1 | method (public getAddress ()) | field(private street)

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

The following chain command types are available:

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 public getAddress 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

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

The syntax should look like the following:
<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.

Static Method Command Examples
  • 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:

The syntax should look like the following:
<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:

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