Products
 
 
 
Fully featured low overhead profiler for Java EE
and Java SE platforms.
Easy to use performance and memory profiler for .NET framework.
Supports ASP.NET, Silverlight, .NET Windows services and more.
previous      content      next
Startup options

What are the startup options?

The startup options allow to customize some aspects of profiling. These options can be configured when you start the profiled application.

When should I specify the startup options?

In most cases, you do not have to specify any of these options, because default behavior suits fine in most cases.

How can I specify the startup options?

These options can be configured when you start the profiled application:

The options are comma-separated if you specify more than one option.

Description of the startup options


Main options

These options can be switched on startup only, i.e. corresponding behavior cannot be altered during runtime.
port=<value>

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

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.

listen=<ip>:<port>

Same as port but this binds agent socket to a particular IP only

onlylocal

Allow only local connections to the profiled application

delay=<milliseconds>

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

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

The telemetry is collected via so called platform MBeans ("managed beans") - the components for monitoring and managing the JVM. Some Java EE 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 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 EE server to ensure that any Java EE 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 seconds delay is not enough in your particular case, try a bigger value.

telemetrylimit=<hours>

The telemetry information is remembered inside the profiler agent. This allows to connect to profiled application on demand, being able to discover how the application has 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 telemetrylimit option you can customize the time period within which the telemetry data is being stored.

Do not use unnecessarily long buffers

Extending the telemetry buffer will allocate additional amount of memory in the profiled application's address space. That is especially important for 32-bit JVMs configured to use big heap (-Xmx) because total process memory is limited to 2-4 GB (depends on OS) and JVM failure may happen if enough memory is not available outside the heap space.

Also, the longer the buffer, the more time it takes to retrieve the telemetry information from the profiler agent when you connect to a long running profiled application.

The limit is not exact

It is not guaranteed that data will be kept within exactly specified hours. hours is rather an approximation; the actual time may slightly (+/- 5 minutes) differ to ensure best performance.

telemetryperiod=<milliseconds>

Specify how often telemetry information is obtained.

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

Note that setting smaller period can add overhead.

probetablelengthlimit=<rows>

Probes: limit the number of rows to be stored by the profiler agent per table. Read more...

deadthreadlimit=<threads>

Specify the number of recently finished threads for which CPU sampling, tracing and monitor 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.

onexit=memory

Always capture a memory snapshot on profiled application exit.

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

onexit=snapshot

Always capture a performance snapshot on profiled application exit.

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

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

dir=<directory for snapshots>

Specify custom snapshot directory for the particular profiled application

logdir=<directory>

By default, the profiler agent log file is <user home>/.yjp/log/<session name>-<PID>.log

Use this option to create logs in different directory.

For example, it can be useful when profiling applications running as a Windows service. They usually run under special user, thus the logs are located in that special user's home directory. For example, it can be C:\WINDOWS\system32\config\systemprofile. It can be difficult to find that directory and to open it in explorer.

Instead, make the logs created in an arbitrary easily accessible directory, e.g. logdir=c:\log

united_log

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

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

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

Running number starts with 1. If the first log file <session name>.1.log exceeds the size limit, a new log file <session name>.2.log will be created and used, then <session 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.

sessionname=<name>

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 session name is automatically chosen for particular application basing 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 IDE.

sampling_settings_path=<file path>

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.txt, where user home corresponds to the account under which a profiled application is launched.

tracing_settings_path=<file path>

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.txt, where user home corresponds to the account under which a profiled application is launched.


Control which profiling modes are turned on right from the start

Note that you do not have to perform measuring right from the start. Instead, in many cases it's better to start or stop measuring at a later moment - from the UI or by using the Profiler API.
sampling

Application will launch with CPU sampling turned on. Note that you do not have to profile CPU right from the start; instead, in many cases it's better to start or stop measuring at a later moment - from the UI or by using the Profiler API.

tracing

Application will launch with CPU tracing turned on. Note that you do not have to profile CPU right from the start; instead, in many cases it's better to start or stop measuring at a later moment - from the UI or by using the Profiler API. This option cannot be used in combination with disabletracing.

alloceach=<N>

Application will launch with object allocation recording started and record each N-th allocation. This option can be used in combination with allocsizelimit. This option cannot be used in combination with disablealloc.

Note that you do not have to record allocations right from the start; instead, you can start or stop recording later from the Profiler or using Profiler API.

allocsizelimit=<B>

Application will launch with object allocation recording started and record allocation of objects with size bigger or equal B bytes. This option can be used in combination with alloceach. This option cannot be used in combination with disablealloc.

Note that you do not have to record allocations right from the start; instead, you can start or stop recording later from the Profiler or using Profiler API.

allocsampled

Use sampled object allocation recording. This option influences only object allocation recording started alloceach and allocsizelimit.

monitors

Launch Java application with started monitor profiling. Note that you do not have to profile monitor usage right from the start; instead, you can start or stop recording later from the Profiler or using Profiler API.

usedmem=<percent>

Automatically capture a memory snapshot when used heap memory reaches the threshold.

Note: this option just adds corresponding trigger on startup. Use triggers directly for a more sophisticated functionality.

usedmemhprof=<percent>

Automatically capture a HPROF snapshot when used heap memory reaches the threshold.

Note: this option just adds corresponding trigger on startup. Use triggers directly for a more sophisticated functionality.

periodicperf=<period in seconds>

Periodically capture performance snapshots.

Note: this option just adds corresponding trigger on startup. Use triggers directly for a more sophisticated functionality.

periodicmem=<period in seconds>

Periodically capture memory snapshots in the profiler's format (*.snapshot).

Note: this option just adds corresponding trigger on startup. Use triggers directly for a more sophisticated functionality.

periodichprof=<period in seconds>

Periodically capture HPROF snapshots.

Note: this option just adds corresponding trigger on startup. Use triggers directly for a more sophisticated functionality.

disablestacktelemetry

Do not collect thread stack and status information shown in Thread view as well as in other telemetry views. This information can be very useful because it allows you to connect to the profiled application on demand and discover how the application behaved in the past. In most cases, there is no significant overhead of collecting this information. However, it makes sense to disable it in production Java EE servers in order to ensure minimum profiling overhead.

See also: Profiling overhead: how to reduce or avoid.

disableexceptiontelemetry

Do not collect exception telemetry. The exception telemetry helps discovering performance issues and logic errors. In most cases, there is no significant overhead of collecting this information. However, it makes sense to disable it in production Java EE servers in order to ensure minimum profiling overhead.

See also: Profiling overhead: how to reduce or avoid.

disableoomedumper

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.

probe_on={full qualified probe class name or pattern}

probe_off={full qualified probe class name or pattern}

probe_auto={full qualified probe class name or pattern}

probe_disable={full qualified probe class name or pattern}

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

probeclasspath=<classpath>

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

probebootclasspath=<classpath>

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

triggers=<file path>

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.


Optimization options

Reduce profiling overhead by disabling some profiling capabilities.
See also: Profiling overhead: how to reduce or avoid.

These options can be switched on startup only, i.e. corresponding behavior cannot be altered during runtime.
disablealloc

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

See also: Profiling overhead: how to reduce or avoid.

disabletracing

Do not instrument bytecode with instructions needed for CPU tracing. Only CPU sampling will be available.

See also: Profiling overhead: how to reduce or avoid.

disableall

Disable several capabilities at once: disablealloc, disabletracing, disableexceptiontelemetry, disablestacktelemetry, probe_disable=*


Miscellaneous
help

Print brief description of startup options.


previous      content      next