Java Probe Parameters

nudge.properties file can be made optional by providing parameters as JVM system properties.

MANDATORY CONFIGURATION

Some parameters can benefit from hot reloading (since version 4.0.0), ie they can be modified in the configuration file without restarting the server. Hot reloading can be disabled using the allow_hot_reloading parameter.

Hot-reloadable parameter list

ignored_params
capture_params
allowed_params
capture_headers
ignored_headers
allowed_headers
httpclient_ip
compressed
profiling_thread_depth
profiling_sample_max_time
max_mbean_attributes_monitored
mbeans_monitored
prepend_tx_type
allow_instance_config
disk_fallback_max_send
disk_fallback_ignore_threshold
disk_fallback_max_size
disk_dump_max_size
system_sample_max_time
disk_fallback_directory
disk_dump_directory
service_qualifier

app_id

Defines which application declared on Nudge portal this JVM belongs to. This is the identification key for your application that allows the information sent by the JVM to application declared on the Nudge portal.

When you download zip file from application settings, the provided nudge.properties file contains this identifier. If you reuse probe on another application, you should update this parameter in order to send data to another application.

When application is hosted on multiple JVMs, for example in a cluster, a single value can be shared between instances. As a result, all transactions will be grouped in the same application on Nudge APM portal.

From a security perspective, this parameter defines application identity for data collection, you should make sure that this value is kept secret.

server_url

For trial purpose use value : server_url=https://ph-apm.eval.atakama-technologies.com/
For existing clients, use provided by support value or please contact support
For new clients please contact : support@atakama-technologies.com to have access to value : server_url=https://ph-apm.<clientname>.collector.atakama-technologies.com/

Defines which Nudge portal to use, should target a local instance when deployed On-Premises, or leave default to use SaaS instance.

Hot reloading

allow_hot_reloading

This parameter is used to disable properties hot reloading (value: false, default value : true). In some rare cases, the server or the java machine fails to stop this parallel process on shutdown or restart ; this setting avoids this problem.

Java 17 compatibility

excluded_classpath

The probe is fully compatible with Java 17 from version 3.6.1 However, this compatibility implies the exclusion of certain package(s) from the instrumentation. It is therefore necessary to add the following parameter to your nudge.properties file:

excluded_classpath=jdk.proxy2

Tests conducted on our environments have shown that in some cases, excluding the jdk.proxy2 package alone is not enough. If you encounter problems launching the agent, modify the configuration as follows:

excluded_classpath=jdk.proxy2,jdk.proxy3

If despite these modifications, the probe does not work correctly with your Java 17 application, please contact us on the Atakama support website.

General

enable

Default value: true

Allows to disable probe without changing JVM command line.

handlers

Default value: http

List of destinations to send data, comma separated. Valid values are : http and file

http makes probe send data to nudge portal.
file makes probe store data in disk_dump_directory folder without sending to nudge portal.
file,http makes both : send to portal and store to disk.

You should also configure disk_dump_directory and disk_dump_max_size to control where and how much should be stored.

It may take a significant amount of space depending on your application activity.

configuration_location

Default value : system-file

Configuration mode of probe and priority.

system-file
1. JVM system parameters
2. nudge.properties file if it exists
3. default value
system : ignores nudge.properties file
1. JVM system parameters
2. default value
/path/to/my/configuration.properties : use a custom configuration file
1. JVM system parameters
2. /path/to/my/configuration.properties file if it exists
3. default value

service_hostname

Default value : null

Available from version 3.1.x

Allows to override detected hostname, should be used when :

deployed in a PaaS where actual hostname is a container and should be overloaded with a “logical name” to make sense.
when machine is unable to resolve its own hostname
when you need to hide actual hostname

service_qualifier

Default value : null

Available from version 3.1.x

Allows to add a suffix to hostname to make service naming easier.

Should be used when multiple JVMs execute on a shared host and need to be distinguishable on monitoring, by default they all be named with host name.

This parameter can be modified without restarting the server (since version 4.0.0).

collector_enable

Default value : true

Available from version 3.2

Controls data collection, set to false to disable. Can also be dynamically changed at runtime through JMX.

Components

Components is available from version 3.2.

component_scan

Default value : true

When enabled, probe will automatically fingerprint application .jar files Will also cover container components.

This allows to track components usage :

does runtime classpath matches expected classpath ?
integrity/security : has any .jar file have been tampered with ?
architecture : which components application relies on ?

We only track components when used, thus :

there is no classpath scanning, components will only include what is used.
it requires realistic application activity to detect all parts.

System

System metrics is available for versions 3.1.x.

system_sample_enable

Default value : true since 3.1.1, false before

Controls if system metrics sampling is enabled.

system_sample_interval

Default value : 60000 (1 minute)

Controls system metrics sampling period.

system_sample_max_time

Default value : 100 (100 ms)

Controls system metrics maximum sampling duration, sample rate is reduced above this threshold.

This parameter can be modified without restarting the server (since version 4.0.0).

Corba

log_corba

Default value : true

Controls CORBA instrumentation.

EJB

log_ejb3

Default value : true

Controls EJB3 instrumentation.

If you have EJB2, you can use trace_classpath_regex, @Trace annotation from nudge probe API, or contact support for other options.

RUM

activate_rum

Default value : false

Controls RUM javascript injection in HTML pages generated by Application Server (JSP, Servlets, …) Required to provide browser-level metrics on portal.

Runnable & Threads

log_runnable

disabled by default from version 3.0.x

Contact support if you need to track Runnables & Threads in your application.

Profiling

profiling_enable

Default value : true

Available for version >= 3.0.10

Controls if sample-based profiling is active.

profiling_thread_depth

Available for version >= 3.0.10, earlier versions should use thread_depth.

Default value : 1000

Maximum thread depth to capture, a low value minimizes profiling data weight but makes profiling less precise. Unless asked to, you should not change this value.

This parameter can be modified without restarting the server (since version 4.0.0).

profiling_sample_interval

Available for version >= 3.0.10

Default value : 1000

Profiling sampling interval, in milliseconds.

By default, probe takes a snapshot of running transactions every second.

If your transactions are very fast or you have only few transactions per day and you need an improved accuracy, which translates to “more samples”, you should lower this value.

With great power comes great responsability

We advise to use this parameter with care and to monitor probe activity in order to find a sensible “samples count” vs “profiling frequency”.

profiling_sample_max_time

Available for version >= 3.0.10

Default value : 10

Maximum allowed time for Profiling sampling in milliseconds. Frequency is reduced when reaching this value to limit overhead.

This parameter can be modified without restarting the server (since version 4.0.0).

RMI

log_rmi

Default value : true

Controls RMI instrumentation.

AOP

AOP (Aspect Oriented Programming) defines a way to define which methods are instrumented in your code. It allows to monitor custom transactions & layers that do not fit any JEE standard natively supported.

trace_classpath_regex

This parameter identifies particular java method(s). These methods will be monitored as particular transactions (or as particular software layers depending on the configuration).

When should I use it?

It’s usually used for processings that the probe doesn’t know how to detect automatically, like for example:

Use of APIs that are not yet supported automatically by the probe,
Batch processings (a method is called periodically),
Asynchronous processings (the processing of a transaction triggers a new processing in another thread),
Concurrent processings (when the processing of a transaction is split into several threads)

It enables to monitor asynchronous or concurrent processing. Indeed, the transaction calls detected by the probe are bound to a given thread during runtime. If the processing of a transaction is split into several threads, then a part of the processing goes outside the detection scope of the probe.

For versions 3.x and beyond

The parameter uses an AOP syntax with comma-separated values. Methods are observed either as transactions or as layer.

Each item is defined by 5 attributes:

Visibility : can be either public, protected, package, private or * (that would match all types of visibility)
package : the name of the java package(s). It can end with a wildcard * for a broad match.
method : the name of the method(s). It can contain with a wildcard * for a broad match.
name : the name of the corresponding transaction or layer. That name will appear in the gathered data and from the Nudge platform.
type : Optional value that can be either layer (by default) or tx. Indicates if it should define respectively a layer or a transaction.

Here are examples :

* com.xyz.service.* * Service tx : All methods of the com.xyz.service package are instrumented as Service transactions.
public org.slf4j.impl.Log4jLoggerAdapter * Log4j layer : create a “Log4j” layer from slf4j to monitor logging as a layer.

For versions before 3.x

The parameter uses an AOP syntax with comma-separated values. Methods are observed as transactions.

Each item is defined by 3 attributes:

Visibility : can be either public, protected, package, private or * (that would match all types of visibility)
package : the name of the java package(s). It can end with a wildcard * for a broad match.
method : the name of the method(s). It can contain with a wildcard * for a broad match.

Here are examples :

public * * : All public methods are instrumented,
* * set : All methods whose name begins with set are instrumented,
* com.xyz.service. : All methods of the com.xyz.service package are instrumented,
* com.xyz *.Dao : All methods within classes with names that begin with Dao in the package (or sub package) com.xyz are instrumented.

With inner-classes

Methods of inner classes can also be configured with the help of wildcards. Here is an exemple of configuration with an inner-class :

trace_classpath_regex=* com/acme/feature/WrappingClass* method

Annotation driven alternative

This parameter makes possible to detect new transactions without any modification in the application code. An alternative approach is the use of the @Trace annotation that is well known by the probe. That annotation tells the probe to add the annoted method as a transaction (or layer). This other solution needs a modification of code. You can find detailed information about the annotation in its dedicated public projet.

JMX

activate_jmx

Deprecated since version 3.3.
Default value : false

Enables or disables JMX sampling.
Since version 3.3, the mbean monitoring is enabled when mbeans are specified to be monitored.

mbeans_monitored

List of MBeans to sample. Only the MBeans of this list will be available from Nudge. If many, the MBeans objectNames should be separated with a semicolon.

Here is an example where the objectName refers to a MBean exposed by Tomcat:

mbeans_monitored=Catalina:type=RequestProcessor,worker="http-bio-8080",name=HttpRequest1

The same MBean can also be retrieved with a wildcard like any of the following examples:

mbeans_monitored=Catalina:type=RequestProcessor,worker="http-bio-8080",name=*
mbeans_monitored=Catalina:type=RequestProcessor,*

With wildcards, all corresponding MBeans will be considered. Please be aware of different uses of wildcards between J2SE 5.0 and Java SE 6. These differences are explained on the Oracle website.

You can consider several MBeans and group of MBeans with the use of semicolon(s):

mbeans_monitored=com.mycompany.mymbean:type=mytype;Catalina:type=RequestProcessor,*

This last example will consider all Catalina:type=RequestProcessor,* MBeans but also the MBean com.mycompany.mymbean:type=mytype. For better readability, you can also write the same this way:

mbeans_monitored=\
com.mycompany.mymbean:type=mytype;\
Catalina:type=RequestProcessor,*

By default, every numeric attributes of MBean are captured by the agent.
Since version 3.3, it is possible to specify which attribute the agent should capture by adding a space and e comma separated list of attributes names:

mbeans_monitored=\
com.mycompany.mymbean:type=mytype attr1,attr2,attr3;\
Catalina:type=RequestProcessor,*

This parameter can be modified without restarting the server (since version 4.0.0).

max_mbean_attributes_monitored

Default value : 2000

Probe records all Mbean attributes, up to this limit. Maximum number of recorded attributes for each MBean.

This parameter can be modified without restarting the server (since version 4.0.0).

jmx_sample_interval

Available for version >= 3.0.10

Default value : 10000 (10s)

Jmx sampling interval, in milliseconds. Minimal value : 10s, which translates to 6 samples per minute on portal.

jmx_sample_max_time

Available for version >= 3.0.10

Default value : 100 (100ms)

Maximum allowed time for JMX sampling in milliseconds. Frequency is reduced when reaching this value to limit overhead.

HTTP

HTTP parameters and headers might be confidential informations so the agent does not capture any of those by default.
But, sometime those informations could be useful:

in order to group transactions in a useful way
in case of an issue on a transaction because these information can help to fix

To meet this need, the agent has parameters allowing to specify informations that are allowed to be captured and provided to the Nudge controler and the monitoring interface.

This feature works for GET requests as well as for POST requests.

capture_params

Default value : false

Enables HTTP parameters capture.

When this parameter is enabled, it is mandatory to define a white list (allowed_params) and/or a black list (ignored_params) of parameters allowed to be captured by the agent.
These two lists can be combined by following these rules:

by activating the two lists ‘allowed’ and ‘ignored’, the parameters present in ‘allowed’ will be taken into account and those in ‘ignored’ will be ignored
if a parameter is part of both lists, it will be ignored because it is present in the ‘ignored’ list
‘allowed’ parameter can be declared alone
you cannot declare only the ‘ignored’ list otherwise all the parameters will be ignored (none will be present in the ‘allowed’ list)

This parameter can be modified without restarting the server (since version 4.0.0).

ignored_params

Default value: (empty)
Example: ignored_params=password,card_number

ignored_params is a comma separated list. It specifies the parameters that the agent must ignore inside HTTP requests.
For example, let’s consider this configuration: ignored_params=password,card_number and an HTTP request with parameters login, password and action then the agent will keep and provide to the Nudge controler only login and action for this transaction.

This parameter can be modified without restarting the server (since version 4.0.0).

allowed_params

Default value: (empty)
Example: allowed_params=login,action

allowed_params is a comma separated list. It specifies the parameters that the agent must ignore inside HTTP requests.
For example, let’s consider this configuration: allowed_params=login,action and an HTTP request with parameters login, password and action then the agent will keep and provide to the Nudge controler only login and action for this transaction.

This parameter can be modified without restarting the server (since version 4.0.0).

capture_headers

Default value: false

Enables HTTP headers capture.

When this parameter is enabled, it is mandatory to define a white list (allowed_headers) and/or a black list (ignored_headers) of headers allowed to be captured by the agent.
These two lists can be combined by following these rules:

by activating the two lists ‘allowed’ and ‘ignored’, the parameters present in ‘allowed’ will be taken into account and those in ‘ignored’ will be ignored
if a parameter is part of both lists, it will be ignored because it is present in the ‘ignored’ list
‘allowed’ parameter can be declared alone
you cannot declare only the ‘ignored’ list otherwise all the parameters will be ignored (none will be present in the ‘allowed’ list)

This parameter can be modified without restarting the server (since version 4.0.0).

ignored_headers

Default value: (empty)
Example: ignored_headers=Authorization,Proxy-Authenticate

ignored_headers is a comma separated list. It specifies the headers that the agent must ignore inside HTTP requests.
For example, let’s consider this configuration: ignored_headers=Authorization,Proxy-Authenticate and an HTTP request with headers Authorization and Cookie then the agent will keep and provide to the Nudge controler only Cookie for this transaction.

This configuration is case insensitive: ignored_headers=Authorization and ignored_headers=AUTHORIZATION will have the same effect.

This parameter can be modified without restarting the server (since version 4.0.0).

allowed_headers

Default value: (empty)
Exemple: ignored_headers=Cookie,Accept

allowed_headers is a comma separated list. It specifies the headers that the agent must ignore inside HTTP requests.
For example, let’s consider this configuration: allowed_headers=Cookie,Accept and an HTTP request with headers Authorization and Cookie then the agent will keep and provide to the Nudge controler only Cookie for this transaction.

This configuration is case insensitive: allowed_headers=Cookie and allowed_headers=COOKIE will have the same effect.

This parameter can be modified without restarting the server (since version 4.0.0).

http_client_ip

Default value: false

This property allows to capture user IP adresses who making transactions.

Parameter available from version 3.2.5, prior to this the IP adresse was always captured.

This parameter can be modified without restarting the server (since version 4.0.0).

log_servlet_contextlistener

Default value: false

Creates a transaction for web application startup and shutdown. Allows to diagnose those deployment phases.

Include/Exclude

During the instrumentation, the agent does two things: check if the classes has to be instrumented and the instrumentation it. These parameters might improve the loading time of the application by avoiding to load all the informations for every class and each type of instrumentation.

excluded_classpath

Black list of packages or classes containing classes that must not be instrumented.

Separator : , (commaservice_qualifier)

Example (a package exclusion and a class exclusion) :

excluded_classpath=oracle.oc4j.sql.proxy,com.acme.impl.SomeClass

included_classpath

White list of packages containing classes that might be instrumented.

excluded_classloaders

Black list of classloaders loading classes that must not be instrumented.

SQL

query_anonymization

Default value : true

long_query_threshold

Default value : 0 (disabled)

When an SQL query is usually fast but some times takes too much time to execute, it is hard to reproduce the issue. This kind of problem are usually caused by some specific values of the query’s parameters.
When using a non-zero value for long_query_threshold, SQL queries that takes more time than this threshold (in milliseconds) will be sent without anonymization in order to help reproduce and fix the issue.

query_count_limit

Default value : 10000

Maximum number of SQL queries sent in each probe message (around one by minute) to the Nudge APM collector

log_connection

Default value : false

Logging

log_level

Default value: INFO

The possibles values (or levels) in descending order are: SEVERE (highest value), WARNING, INFO, CONFIG, FINE, FINER, FINEST (lowest value).

log_level is the parameter that controls the log level the probe uses. By default the log level is INFO, which is suitable for production environments. When you install the agent for the first time, or when you want to validate its operation in an application, it is recommended you set its value to FINE.

log_directory

Directory used for logging. It will be created if it does not exists.

The default directory is the log folder next to the probe jar file.

When you have multiple JVMs on the same host, you should make sure that each JVM instance have its own dedicated folder.

log_rotation_count

Default value: 5

Number of log files to keep. Log rotation is done at each JVM startup.

upload_log

Default value: true

Uploads probe log to nudge platform to report any errors and make support easier.

fine_log_on_startup

Default value: true

Raise log level to FINE for few minutes after startup.

Makes support easier by providing valuable information to troubleshoot any startup issue.

allow_instance_config

Default value: true

Enable JVM instance properties collection. When disabled, not all JVM parameters are available on Nudge portal.

This parameter can be modified without restarting the server (since version 4.0.0).

upload_config

Default value: true for 3.0.x versions, false for 3.1.x.

Uploads probe configuration to nudge platform to make support easier.

Flush

Probe stores collected metrics in-memory, and then flushes collected data to Nudge portal asynchronously. These parameters control which events trigger a flush.

Default values fit most applications, however if you have a high transaction volume (> 1000tx/min or more), you may need to adapt these settings in order to minimize probe memory overhead.

flush_tx_count

Default value: 2000

Number of transactions to trigger a flush

flush_thread_samples_count

Default value : 5000

Number of thread samples to trigger a flush

flush_jmx_samples_count

Default value : 1000

Number of jmx samples to trigger a flush

flush_system_samples_count

Default value : 1000

Number of system metrics samples to trigger a flush

flush_components_count

Default value : 1000

Number of detected components to trigger a flush

flush_rum_count

Default value : 1000

Number of RUM samples to trigger a flush

flush_interval

Default value : 60 (1 minute)

Time interval between two scheduled flushes in seconds.

flush_overflow_limit_factor

Default value : 5

Controls maximum number of items be kept in-memory waiting for flush. This factor is applied to all flush_*_count parameters above to define limit.

By default, a value of 5 makes probe keep at most 5 x 2000 = 10000 transactions in-memory. When limit is reached, new transactions are ignored, and monitoring becomes partial.

Network

proxy_type

Default value : http

proxy_host

Proxy server hostname or IP

proxy_port

Proxy server port

proxy_user

Proxy user, leave blank or omit parameter to bypass authentication.

proxy_password

Proxy password

compressed

Default value: true

Controls if probe sends data to portal using compression.

With compression enabled, sent data is reduced by 90%, makes agent use sligtly more CPU.

This parameter can be modified without restarting the server (since version 4.0.0).

network_connect_timeout

Default value : 2000 (2s)

Nudge Portal connexion timeout in milliseconds.

network_read_timeout

Default value : 5000 (5s)

Nudge Portal data send timeout in milliseconds.

packet_size

Disk Usage

disk_dump_directory

Default value: log_directory

Controls where data is stored when using handlers = file

This parameter can be modified without restarting the server (since version 4.0.0).

disk_dump_max_size

Default value: -1 (unlimited)

Controls maximum amount of data (in bytes) should be kept when using handlers = file

This parameter can be modified without restarting the server (since version 4.0.0).

disk_fallback_directory

Default value: log_directory

Controls where data is stored when Nudge Portal is unreachable.

This parameter can be modified without restarting the server (since version 4.0.0).

disk_fallback_max_size

Default value: 209715200 (200Mb)

Controls how much data (in bytes) is kept when Nudge Portal is unreachable.

This parameter can be modified without restarting the server (since version 4.0.0).

disk_fallback_ignore_threshold

Default value: 86400 (24h)

Controls how long (in seconds) fallback files should be kept before being discarded. When Nudge Portal is not reachable.

Data will be discarded when Nudge Portal is unreachable for a period longer than this parameter.

This parameter can be modified without restarting the server (since version 4.0.0).

disk_fallback_max_send

Default value: 10

Controls how much fallback files should be sent when connection to Nudge Portal have been restored.

This parameter can be modified without restarting the server (since version 4.0.0).

Other

Those features are provided for convenience and troubleshooting only, you should not rely on them. We may change or remove them in future versions.

dryrun

Default value: false

Allows to disable application instrumentation while keeping JMX sampling and data collection active. Should only used for troubleshooting, when enabled no transaction will be monitored.

thread_dump_frequency

Frequency of a thread dump catpure, in second.
This parameter is related to thread_dump_duration.

Default value : 0 (disabled)

thread_dump_duration

Automatically schedule thread dumps after JVM startup for a duration in second.
This parameter is active if thread_dump_frequency is > 0.

Default value : 0 (disabled)
Example: execute a thread dump every second for 10 seconds after the JVM startup.
```
thread_dump_frequency=1
thread_dump_duration=10
```

prepend_tx_type

Default value: false

Prefix transaction names with their type.

This parameter can be modified without restarting the server (since version 4.0.0).

dump_classes

Default value: false

Dumps instrumented classes before and after transformation into log_directory.

dump_all_classes

Default value: false

Dump all application classes into log_directory.

instrumented_code_stacktraces

Default value: false

Write in log the stacktrace of an instrumented method, this is particularly verbose but useful for debugging purpose.