Agent startup options

port=<port>

or

port=<min port>-<max port>

Specify the port that the profiler agent listens on for communication with the profiler UI.

By default, the port is chosen automatically: if port 10001 is free, it is used; otherwise, if port 10002 is free, it is used etc. If no port in the range 10001..10010 is free, an arbitrary free port is used.

If port range is specified, profiler will choose first free port in the range.

Specify the profiler agent connectivity option.

• Most security, the default option: listen=localhost opens the profiler agent socket on the IPv4 loopback network interface. The most commonly used IP address on the loopback network is 127.0.0.1. This will disable a direct remote connection to the agent via <host>:<port>. Connection to the profiler agent will be possible via port forwarding e.g. an SSH tunnel.
• Easy access: listen=all opens the profiler agent socket on all network interfaces. A remote connection to the agent will be possible directly via <host>:<port>. Note that access to the port can be additionally restricted with a firewall.
• Advanced: listen=<IP> opens the profiler agent socket on the specified IP address.
• Block all incoming connections: listen=none blocks all incoming agent connections. Option is automatically applied when broker_url is specified.

File with the SSL certificate in the PEM format.

If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates.

If the ssl_certificate option is absent, the agent will create self-signed certificate.

File with the secret key in the PEM format.

If the secret key ssl_certificate_key is encrypted, then the first line of the specified password file will be used as a password (passphrase).

Connection broker URL.

Connection broker access token.

Don not immediately start CPU profiling that can instead be started later in runtime. This is the default.

Immediately start CPU profiling in the sampling mode.

Immediately start CPU profiling in the asynchronous CPU sampling mode.

Immediately start CPU profiling in the asynchronous periodic sampling mode.

Immediately start CPU profiling in the tracing mode.

Immediately start CPU profiling in the call counting mode.

Specify a custom location of the CPU sampling settings configuration file.

If this option is not specified, the settings are read from <user home>/.yjp/sampling_2022.txt, where user home corresponds to the account under which a profiled application is launched.

Specify a custom location of the CPU tracing settings configuration file.

If this option is not specified, the settings are read from <user home>/.yjp/tracing_2022.txt, where user home corresponds to the account under which a profiled application is launched.

Do not immediately start object allocation profiling that can instead be started later in runtime. This is the default.

Immediately start object allocation profiling in the bytecode instrumentation mode.

Immediately start object allocation profiling in the heap sampling mode.

Immediately start object allocation profiling in the object counting mode.

A default interval for bci and heap_sampling allocation profiling modes. When the total bytes allocated by a Java thread exceed the specified interval, the profiler records the allocation details.

Immediately start telemetry collection. This is the default mode.

Do not immediately start telemetry collection that can instead be started later in runtime.

The telemetry and thread profiling results are remembered in a circular buffer in the profiler agent memory. This allows you to connect to a profiled application on demand and discover how the application behaved in the past.

By default, the telemetry buffer is limited to store approximately 1 hour of recent telemetry data.

With the help of the telemetry_limit option you can customize the time period within which the telemetry data is being stored.

Specify how often telemetry and thread profiling information is obtained.

By default, the period is 1 second (1000 milliseconds).

Note that setting smaller period can add overhead.

The threads option regulates the collection of data specific to the threads within a profiled application. In most cases, collecting this information does not result in significant overhead. However, it is sensible to turn it off on production servers to ensure minimal profiling overhead.

• full - The default value. Collect both thread states and stacks.
• states - Collect only thread states.
• off - Do not collect thread states and stacks.

Enable periodic JVM deadlock checks. This is the default mode.

Disable periodic JVM deadlock checks.

Specify how often deadlock checks are performed. By default, the period is 300 seconds (5 minutes).

Enable exception events in the JVM and immediately start the exception profiling. This is the default mode.

Enable exception events in the JVM but do not immediately start the exception profiling that can instead be started later in runtime.

Fully disable exception profiling and totally eliminate related overhead. The exception profiling will not be available.

Immediately start monitor profiling.

Do not immediately start monitor profiling that can instead be started later in runtime. This is the default.

Immediately start flight recording at application startup, using the jfr_config_name configuration and the jfr_max_size recording size.

Do not start flight recording at application startup. The recording can be started later during application runtime. This is the default.

Optional name of the flight recording configuration to start at application startup. If not specified, the profile configuration is used. For example: jfr_config_name=default.

Optional maximum size of the flight recording started at application startup. Use 0 for unlimited size. If not specified, the agent chooses a default recording size.

Specify custom snapshot directory for the particular profiled application

Specify alternate rule to compose snapshot file names.

Available macros:

• {app_name} - application name
• {date} - snapshot capture date in format 'yyyy-MM-dd'
• {datetime} - snapshot capture date and time in format 'yyyy-MM-dd-HH-mm'
• {pid} - profiled process ID

The default format is {app_name}-{date}.

Characters not allowed in file names, if specified, will be replaced with '-'.

Capture JFR snapshot on profiled application exit.

If this option is not specified, the JFR snapshot will be captured on exit if flight recording is running at that moment.

Capture HPROF memory snapshot on profiled application exit.

Capture a memory snapshot on profiled application exit.

Capture a performance snapshot on profiled application exit.

If this option is not specified, the performance snapshot will be captured on exit if CPU profiling, monitor profiling or object allocation profiling is running at that moment.

This option is automatically added when the profiled application is started from the IDE.

Specify the file with description of the triggers to be applied from startup.

If this option is not specified, the trigger description is read from <user home>/.yjp/triggers.txt, where user home corresponds to the account under which a profiled application is launched.

By default, that file does not exist, thus no triggers are applied.

Adds a trigger to automatically capture a memory snapshot when used heap memory reaches the threshold.

Adds a trigger to automatically capture HPROF snapshot when used heap memory reaches the threshold.

Adds a trigger to periodically capture performance snapshots.

Adds a trigger to periodically capture memory snapshots in the profiler's format (*.snapshot).

Specifies the top-level directory where a trigger action is allowed to create or modify files. All file paths used in a trigger action are interpreted as relative to this directory.

By default, the directory is set to <user home>/.yjp/triggers_out/, where <user home> refers to the home directory of the user running the profiled Java process.

The purpose of triggers_out_dir is to restrict trigger actions from reading or modifying files, ensuring that all file operations are confined to a safe, dedicated directory.

probe_on=<pattern>

probe_off=<pattern>

probe_auto=<pattern>

probe_disable=<pattern>

Specify which probes should be registered on startup. Read more...

Specify where to find probe class(es) which are registered by class name. Read more...

Specify where to find probe class(es) which are registered by class name. Read more...

options_file=<path to options file>

or

@<path to options file>

Specify a path to the options file with agent startup options. Options from the options file will be used as if they were directly specified in its place, in order they are written in the file.

Example: options_file=profiler-options.txt or @profiler-options.txt.

Specify alternate presentable name of the profiled application used in:

• the profiler UI
• snapshot names
• log file name

If this option is not specified, the application name is automatically chosen based on its main jar file name, or its main class name, or the custom executable name, or on the run configuration name when profiling from within the IDE.

The default automatically generated application name can be specified via {default} macro.

For example, to append the host name to the default application name, use app_name={default}-${HOSTNAME} on UNIX and app_name={default}-${COMPUTERNAME} on Windows.

Specifies the directory where profiler agent creates a log file. By default, the profiler agent log file is <user home>/.yjp/log/<application name>-<PID>.log

Use the log_dir option to store logs in a different directory.

This can be particularly useful when profiling applications that run as Windows services. Such services typically run under a special system account, so their logs are placed in that account's home directory (for example: C:\WINDOWS\system32\config\systemprofile). Locating and opening this directory in Explorer can be challenging.

With log_dir, you can redirect logs to any easily accessible directory. For example: log_dir=c:\log

Specify alternate directory for temporary files created by the profiler agent:

• JAR file with built-in probe classes;
• agent-client communication buffer.

By default, the profiler agent creates the temporary files in the default temporary directory.

Store logs from several runs of the same application as a series of log files named <application name>.<running number>.log instead of creating an individual log file <application name>-<PID>.log for each profiled process.

This mode may simplify log maintenance and cleanup when profiling applications such as servers.

Application name is the presentable name of the application; see the startup option app_name=<name> for detail.

Running number starts with 1. If the first log file <application name>.1.log exceeds the size limit, a new log file <application name>.2.log will be created and used, then <application name>.3.log etc. The size limit is 1 MB by default, and can be changed with the startup option log_file_size_limit=<bytes>

Note: the oldest log files are not automatically removed. If you need to clean them up, do it manually or write a script.

Limit the number of rows to be stored by the profiler agent per table. The default value is 100,000. Read more...

Specify the number of recently finished threads for which profiling results are kept. The default value is 50. Profiling results for the finished threads beyond this limit are merged to <Oldest finished threads> pseudo-thread node. The intention is to limit collected data size when profiling applications constantly creating new short living threads.

Postpone start of telemetry collection and deadlock checks. This option is mostly intended to prevent startup issues of some Java servers.

By default, telemetry is collected right from the start of the profiled application.

These features use so-called platform MBeans ("managed beans") - the components for monitoring and managing the JVM. Some Java servers install their own implementations of standard MBeans. In earliest stages of the server startup the MBeans can not be functional because they depend on other components of the server (such as custom logging) which have not initialized so far. Accessing such MBeans in the earliest stages can cause the server startup failure (e.g. with ClassNotFoundException).

The delay option ensures that all MBeans are completely initialized before they are first accessed, by postponing the start of collecting the telemetry.

The Java EE integration wizard by default uses delay=10000 to postpone the telemetry for 10 seconds. Although not all servers (and not all versions of particular server) suffer from the problem with MBeans, it is recommended to always use the delay when profiling a Java server to ensure that any Java server can successfully start. Furthermore, the telemetry of first few seconds of the server startup is unlikely of any interest for you, because the server's internals are being initialized during that time rather than your own application code.

If the 10-second delay is not enough in your particular case, try a bigger value.

Disable on OutOfMemoryError snapshots. Note that enabling on OutOfMemoryError snapshots adds absolutely no overhead. If OutOfMemoryError happens, memory snapshot is written to disk for further analysis. You may want to disable the snapshots in some very special situations, e.g. if you profile an application with a huge heap, for which capturing the snapshot may take significant resources (time and/or disk space), but do not plan to perform its memory analysis.

Do not instrument bytecode with instructions needed for object allocation profiling.

Bytecode instrumentation and object counting mode won't be available.

Disable object allocation profiling in heap sampling mode.

Do not instrument bytecode with instructions needed for CPU tracing. Both CPU tracing and call counting will not be available.

Disables asynchronous sampling capabilities.

Do not wrap native methods for bytecode instrumentation. When this option is specified, native methods will not be shown in CPU tracing results and in events recorded with probes if they depend on native method invocations.

Disable several capabilities at once: alloc=off, cpu=off, deadlocks=off, disable_alloc, disable_async_sampling, disable_heap_sampling, disable_natives, disable_oome_dumper, disable_tracing, exceptions=disable, jfr=off, monitors=off, probe_disable=*, telemetry=off, threads=off

The quiet option suppresses or allows printing occasional agent messages tostdout and stderr, such as printing agent log path at application startup.

• true - The default value. Suppresses agent messages to stdout and stderr.
• false - Allows agent messages to stdout and stderr.

The compression algorithm used when transferring the snapshot:

• none - no compression.
• deflate - deflate algorithm.
• zstd - zstd algorithm.

The default option is zstd.