Application Insights Java Profiler

The Application Insights Java Profiler provides a system for:

1. Generating profiles of the current JVM
2. Monitoring local resource usage and generating a profile if certain conditions are met (such as CPU or memory breaching a configured threshold)

Overview

The Application Insights Java profiler uses the JFR profiler provided by the JVM to record profiling data. So that users may download the JFR recordings at a later time and analyze them to identify the cause of performance issues. This data is gathered on demand when trigger conditions are met. Currently, the available triggers are thresholds over CPU usage and Memory consumption. When a threshold is breached, a profile of the configured type and duration is gathered and uploaded. This profile is then visible within the performance blade of the associated Application Insights Portal UI.

Warning

The JFR profiler by default executes the "profile-without-env-data" profile. This configuration is similar to the "profile" configuration that ships with the JVM, however has had some events disabled that have the potential to contain sensitive deployment information such as environment variables, arguments provided to the JVM and processes running on the system. The flags that have been disabled are:

• jdk.JVMInformation
• jdk.InitialSystemProperty
• jdk.OSInformation
• jdk.InitialEnvironmentVariable
• jdk.SystemProcess

However, you should review all flags enabled to ensure that profiles do not contain sensitive data.

If you wish to provide a custom profile configuration, alter the memoryTriggeredSettings and cpuTriggeredSettings to provide the path to a .jfc file with your required configuration. Profiles can be generated/edited in the JDK Mission Control (JMC) user interface under the Window->Flight Recording Template Manager menu and control over individual flags is found inside Edit->Advanced of this user interface.

USAGE

Installation

1. Inside the applicationinsights.json configuration of your process enable the profiler by setting the preview.profiler.enabled setting:

      {
         "connectionString" : "...",
         "preview" : {
            "profiler" : {
               "enabled" : true
            }
         }
      }

   Alternatively, set the APPLICATIONINSIGHTS_PROFILER_ENABLED environment variable to true.
2. Execute your process with the updated configuration.
3. Configure the resource thresholds that will cause a profile to be collected:
   1. Browse to the Performance -> Profiler section of the associated Application Insights instance.
   2. Select "Triggers"
   3. Configure the required CPU and Memory thresholds. And Apply.
   4. Note, currently the Java profiler does not support the "Sampling" trigger, configuring this will have no effect.

Once this has been completed, the agent will monitor the resource usage of your process and trigger a profile when required. Once a profile has been triggered and completed, it will be viewable from the Application Insights instance within the Performance -> Profiler section. From that screen the profile can be downloaded, once download the JFR recording file can be opened and analyzed within a tool of your choosing.

Configuration

Configuration of the profiler triggering settings, such as thresholds and profiling periods can be performed within the ApplicationInsights UI under the Performance, Profiler, Triggers UI as described in Installation.

Additionally, a number of parameters can be configured using environment variables and the applicationinsights.json configuration file.

Environment variables

• APPLICATIONINSIGHTS_PROFILER_ENABLED: boolean (default false)
  • Enables/disables the profiling feature.

Configuration file

{
  "preview": {
    "profiler": {
      "enabled": true,
      "cpuTriggeredSettings": "profile-without-env-data",
      "memoryTriggeredSettings": "profile-without-env-data",
      "manualTriggeredSettings": "profile-without-env-data",
      "globalCooldownSeconds": 120,
      "enableProfilerControlMBean": false,
      "manualTrigger": {
        "enabled": false,
        "filePath": "applicationinsights-agent-profile-trigger",
        "defaultProfileDurationSeconds": 120
      }
    }
  }
}

memoryTriggeredSettings - This configuration will be used in the event of a memory profile is requested. This can be one of:

• profile-without-env-data (default value). A profile with certain sensitive events disabled, see Warning section for details.
• profile. Uses the profile.jfc configuration that ships with JFR.
• A path to a custom jfc configuration file on the file system, i.e /tmp/myconfig.jfc.

cpuTriggeredSettings - This configuration will be used in the event of a cpu profile is requested. This can be one of:

• profile-without-env-data (default value). A profile with certain sensitive events disabled, see Warning section for details.
• profile. Uses the profile.jfc jfc configuration that ships with JFR.
• A path to a custom jfc configuration file on the file system, i.e /tmp/myconfig.jfc.

manualTriggeredSettings - This configuration will be used for manually triggered profiles (via file trigger or JMX MBean). Accepts the same values as cpuTriggeredSettings.

globalCooldownSeconds - (default: 120) Cooldown period in seconds applied after any profile recording completes, regardless of trigger source. During cooldown, all trigger sources (CPU, memory, request, manual, periodic) are suppressed. Set to 0 to disable (individual trigger cooldowns still apply).

enableProfilerControlMBean - (default: false) Whether to register a JMX MBean (com.microsoft:type=AI-alert,name=ProfilerControl) that allows triggering profiles via JMX tools. See Manual Profile Triggering for usage.

manualTrigger - Configuration for the file-based manual profile trigger:

• enabled - (default: false) Whether the file-based manual trigger is enabled.
• filePath - (default: applicationinsights-agent-profile-trigger) Path to the trigger file. If relative, it is resolved against the agent's temp directory. Creating or touching this file triggers a profile recording.
• defaultProfileDurationSeconds - (default: 120) Duration in seconds for profiles initiated by the file trigger when no override is specified in the collection plan.

Manual Profile Triggering

In addition to automatic threshold-based triggers, profiles can be initiated manually using either the file-based trigger or the JMX MBean.

File-based trigger

When manualTrigger.enabled is true, you can trigger a profile by creating or touching the trigger file:

touch /tmp/applicationinsights-agent-profile-trigger

The file must have been modified within the last 60 seconds to be considered valid (stale files are ignored to prevent unintended recordings after restarts). After the trigger is detected, the file is automatically deleted.

Note: The file trigger is evaluated on the profiler's configuration polling cycle (default every 60 seconds), so there may be up to a one-minute delay between touching the file and the profile recording starting.

JMX MBean trigger

When enableProfilerControlMBean is true, the agent registers a JMX MBean that can be invoked to trigger profiles:

Via jmxterm:

echo "run -b com.microsoft:type=AI-alert,name=ProfilerControl triggerProfile" | \
  java -jar jmxterm.jar -l <pid>

Via JConsole:

Connect to the target JVM process, navigate to the MBeans tab, expand com.microsoft → AI-alert → ProfilerControl, and invoke the triggerProfile operation.

Both manual triggering mechanisms respect the globalCooldownSeconds setting — if a profile was recently recorded, manual triggers will be suppressed until the cooldown expires.