Configuring the Management Pack for Java Application Performance Monitoring

Applies To: System Center 2012 R2 Operations Manager

This section provides guidance on configuring and tuning this management pack.

  • Configure Base Management Pack for Java Enterprise Edition (JEE) Through Deep Monitoring

  • Import Management Packs

  • Manually Deploy Java APM Agent

  • Verify APM Agent Deployment

  • Additional Java APM Agent Configuration

  • Best Practice: Create a Management Pack for Customizations

  • Security Configuration

Configure Base Management Pack for Java Enterprise Edition (JEE) Through Deep Monitoring

Follow the documentation for the Management Pack for JEE to configure through Deep Monitoring, which includes installation of the BeanSpy application. Java Application Performance Monitoring does not function without this required configuration.

Import Management Packs

The management packs include libraries and objects that are specific to the version of Tomcat application server. Import the following library management packs:

  • Microsoft.JEE.APM.Library.mpb

  • Microsoft.JEE.Tomcat.APM.Library.mp

Next, import the management packs that are required for the versions of the application servers that you monitor from the following list:

  • Microsoft.JEE.Tomcat.5.Apm.mp

  • Microsoft.JEE.Tomcat.6.Apm.mp

  • Microsoft.JEE.Tomcat.7.Apm.mp

For information about how to import a management pack see How to Import a Management Pack.

Manually Deploy Java APM Agent

From the Deep Monitored Configurations section under Tomcat in Monitoring, click on an application server to enable the task Extract APM Jar Files. This task extracts the Java agent files to either the monitored computer, for a server that runs the Windows operating system, or to the gateway or management server fora computer that runs Linux. The task output includes the locations of the extracted files. For a computer that runs Linux, you must manually copy the resulting .zip file for the Tomcat application to access the files. Extract the files from the agent, zip them, and then place them in a directory on the monitored computer. Finally, modify the Catalina.bat or Catalina.sh startup scripts to set JAVA_OPTS to enable the APM agent.

Be careful to avoid overwriting existing JAVA_OPTS paths. For example, if you install the agent in C:\apm\, the appropriate path is set as follows:

set AGENT_DIR=\apm
set JAVA_OPTS=%JAVA_OPTS% -Djava.library.path=%AGENT_DIR%
set JAVA_OPTS=%JAVA_OPTS% -javaagent:"%AGENT_DIR%\apm_facade.jar" \
        -Dnative.library.path=%AGENT_DIR% \
        -Xbootclasspath/p:"%AGENT_DIR%\apm_facade.jar" \
        -Xbootclasspath/p:"%AGENT_DIR%\apm_producers.jar"

For Linux, the path is set as follows:

#!/bin/bash

AGENT_DIR=/home/user/apm_agentdir

# Set location for native (DLL/so) library
JAVA_OPTS="$JAVA_OPTS -Djava.library.path=$AGENT_DIR"
JAVA_OPTS="$JAVA_OPTS -javaagent:$AGENT_DIR/apm_facade.jar \
          -Xbootclasspath/p:$AGENT_DIR/apm_producers.jar \
          -Xbootclasspath/p:$AGENT_DIR/apm_facade.jar"

export AGENT_DIR="$AGENT_DIR"
export JAVA_OPTS="$JAVA_OPTS"

Verify APM Agent Deployment

After you install the agent, you can review a log file called apm-java-agent.txt in the directory that Tomcat runs from. If the management pack is properly configured, the file contains an entry that includes the text "Initializing Java APM Agent"

Additional Java APM Agent Configuration

The following configuration files control agent behavior:

  • Starter.properties

  • SEAgent.config.xml

  • Pmonitor.config.xml

Starter.properties

This file contains early initialization settings required to start the Java Vitural Machine (JVM).

Setting name Description Default value

ClassPath

This setting contains a set of JAR files to load for the agent to work by the inner classloader. You generally do not need to modify this setting.

apm_monitor.jar;asm-all-3.3.1.jar;apm_producers.jar

MonitorConfigName

This setting points to the file that contains the producer configuration. You generally do not need to modify this setting.

pmonitor.config.xml

AgentConfigFileName

This setting points to the file that contains agent level configuration options. You generally do not need to modify this setting.

SEAgent.config.xml

LogFileName

This setting points to the file name to log agent information to.

apm-java-agent.log

LogLevel

This setting controls how verbose the Java APM agent logging is A setting of FINEST produces a significant amount of logging. This runs the risk of filling a disk if not monitored.

INFO

SEAgent.config.xml

This file contains settings related to the internal behavior of the APM agent.

Important

In general, we do not recommend changing these settings. If you do change these settings, add overrides to the management packs to make the intervals match your changes.

Setting name Description Default value

eventSender

Controls the internal communication channel for the agent. We do not recommend that you change this setting unless a support provider directs you to do so.

MBeanEventLog

Frequency under appPerfCounters Node

This value, in seconds, controls how frequently the agent stores performance counters on the agent side.

300

WindowLength under troubleshooting Node

This value, in seconds, controls the size of the window of performance counter data to collect and attach to an instance of an event.

900

Frequency under troubleshooting Node

This value, in seconds, controls the interval at which to collect JVM statistics.

30

Frequency under EventSending Node

This value, in seconds, is the interval at which to check the outgoing message queue.

300

The event sender setting always has a namespace under com.microsoft.ManagementServices.APMAgent.EventSender, for example, com.microsoft.ManagementServices.APMAgent.EventSender.MBeanEventLog.

Pmonitor.config.xml

This file contains settings related to what methods to instrument and the thresholds for creating performance events. You can disable data collection from a named application by using this file. The file contains additional documentation for these settings.

Important

We recommend that you do not edit the settings in this file related to resources and entry point definitions unless support personnel instruct to do so.

Setting name Description Default value

<ss:defaultSettings major, minor>

The major value refers to a threshold for entry point in milliseconds. When a resource breaks this threshold, the management pack creates a performance event. The minor value refers to a threshold on a resource in milliseconds. For a resource that breaks the minor threshold, the method gathers additional information.

Major: 5000

Minor: 100

<ss:application enable>

This setting controls event and counter generation on an application by application basis. By adding a row here, you can disable an individual application. By default, the file disables event generation from BeanSpy.

Not Applicable

Best Practice: Create a Management Pack for Customizations

By default, Operations Manager saves all customizations such as overrides to the Default Management Pack. As a best practice, you should instead create a separate management pack for each sealed management pack you want to customize.

When you create a management pack for the purpose of storing customized settings for a sealed management pack, it is helpful to base the name of the new management pack on the name of the management pack that it is customizing.

Creating a new management pack for storing customizations of each sealed management pack makes it easier to export the customizations from a test environment to a production environment. It also makes it easier to delete a management pack, because you must delete any dependencies before you can delete a management pack. If customizations for all management packs are saved in the Default Management Pack and you need to delete a single management pack, you must first delete the Default Management Pack, which also deletes customizations to other management packs.

Security Configuration

This management pack does not include any new Run As profiles.