Java Probe Parameters

This section provides configuration parameters reference for Java probe.

Before using advanced configuration, you should make sure you have properly installed probe using java probe installation procedure.

The Java probe configuration is provided through:

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

General

app_id

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

enable

Default value: true

Allows to disable probe without changing JVM command line.

server_url

Default value: https://collector.nudge-apm.com

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

handlers

Default value: http

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

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.

service_hostname

Default value : null

Available from version 3.1.x

Allows to override detected hostname, should be used when :

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.

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 :

We only track components when used, thus :

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.

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.

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.

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:

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:

Here are examples :

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:

Here are examples :

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,*

max_mbean_attributes_monitored

Default value : 2000

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

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:

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) or a black list (ignored_params) of parameters allowed to be captured by the agent.
Both lists can not be combined.

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.

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.

capture_headers

Default value: false

Enables HTTP headers capture.

When this parameter is enabled, it is mandatory to define a white list (allowed_headers) or a black list (ignored_headers) of headers allowed to be captured by the agent.
Both lists can not be combined.

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.

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.

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.

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.

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.

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.

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

disk_dump_max_size

Default value: -1 (unlimited)

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

disk_fallback_directory

Default value: log_directory

Controls where data is stored when Nudge Portal is unreachable.

disk_fallback_max_size

Default value: 209715200 (200Mb)

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

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.

disk_fallback_max_send

Default value: 10

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

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.

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.

prepend_tx_type

Default value: false

Prefix transaction names with their type.

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.

Java 17 compatibility

The probe is now compatible with Java 17 from version 3.6.0 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.