Instrument Java Applications

AppDynamics Pro Documentation Version 4.0.x

Page 1 Instrument Java Applications ...... 3 Java Supported Environments ...... 6 Install the Java Agent ...... 20 Java Server-Specific Installation Settings ...... 28 Apache Cassandra Startup Settings ...... 28 Apache Tomcat Startup Settings ...... 29 Coherence Startup Settings ...... 33 GlassFish Startup Settings ...... 33 IBM WebSphere and InfoSphere Startup Settings ...... 37 JBoss and Wildfly Startup Settings ...... 41 Jetty Startup Settings ...... 50 Mule ESB Startup Settings ...... 51 Oracle WebLogic Startup Settings ...... 52 OSGi Infrastructure Configuration ...... 55 Resin Startup Settings ...... 58 Solr Startup Settings ...... 59 Standalone JVM Startup Settings ...... 60 Tanuki Service Wrapper Settings ...... 61 Tibco ActiveMatrix BusinessWorks Service Engine Settings ...... 61 webMethods Startup Settings ...... 62 Java Agent Configuration Properties ...... 63 Use System Properties for Java Agent Settings ...... 74 Use Environment Variables for Java Agent Settings ...... 76 Instrument Multiple JVMs on a Single Machine ...... 77 Instrument Dynamically Identified JVMs ...... 78 Instrument JVMs in a Dynamic Environment ...... 79 Instrument JVMs Started by Batch or Cron Jobs ...... 80 Instrument JVMs in Restricted Environments ...... 82 Automate Java Agent Deployment ...... 82 Instrument Apple WebObjects Applications ...... 83 Upgrade the Java Agent ...... 84 Uninstall the Java Agent ...... 85 Administer the Java Agent ...... 86 Java Agent Directory Structure ...... 86 Moving Java Nodes to a new Application or Tier ...... 88 IBM Java Agent ...... 89 Enable SSL for Java ...... 90 Tune Java Agent Performance ...... 95 View Agent Diagnostic Data ...... 97 Start an Agent Logging Session ...... 97 Troubleshooting Java Agent Issues ...... 98 Configure Syslog Logging Output by the Agent ...... 101

Page 2 Instrument Java Applications

On this page: Before You Begin Overview of Instrumenting Your Java Application Configure and Download the Java Agent Automatic Naming in a Self-Service Pro Trial Install the Agent on the App Server View Application Activity in the Controller Related pages: AppDynamics Essentials Quick Install for the Standalone Machine Agent Watch the video: Getting Started: AppDynamics for Java Rate this page:

To monitor Java applications in the Controller, you need to install the AppDynamics Java Agent on each server that hosts applications to be monitored. You then add the Java Agent binary to the Java application process, typically by passing the agent JAR file as a startup argument to the application. This enables the agent to instrument your application and report performance data to the AppDynamics Controller. This page describes how to install the Java Agent using the Agent Download Wizard in the Controller. If you downloaded the agent from the AppDynamics download zone, see Install the Java Agent.

Before You Begin

1. Confirm you have access to a controller, the web application where you monitor your application performance: If you use a SaaS controller, AppDynamics sent you the controller host in your Welcome Email. If you use the on-premise controller, you supplied the host and port at install time. 2. Verify you have root access to run the install on the machine. 3. Verify support for your environment at Java Supported Environments.

Overview of Instrumenting Your Java Application

To instrument your JVM and begin monitoring:

Copyright © AppDynamics 2012-2015 Page 3 1. Setup: Use the Agent Download Wizard to set up and download the agent. 2. Install and configure: Unzip the agent on your server and add it to your JVM startup script. 3. Apply load and view data: Restart your application and apply load to activate instrumentation. The following steps provide an overview of how to install that agent. For details, see Install the Java Agent.

Configure and Download the Java Agent

The Agent Download Wizard walks you through steps for configuring and downloading the Java Agent. The wizard presents a few choices, including the type of JVM type (Sun or JRockit or IBM JVMs) of the application you want to monitor and whether it needs to connect to the Controller with SSL. For SSL, enter the SSL port to use (AppDynamics SaaS instances uses port 443 for SSL). The wizard takes you through a slightly different flow for a self-service trial edition of the Controller versus a non-trial edition: If you are using a self-service Pro Trial edition of AppDynamics Pro, the application and tier names are generated for you and not shown as entries in the wizard. This helps you get started quickly. You can always change these values after you understand how you want to model your environment in AppDynamics. See the following section for the automatic-naming format. If using a non-trial edition, you can configure the application to which the agent will report data and the tier to which the node belongs in the wizard. A node name, the value that identifies an individual JVM in the monitored environment, is generated and inserted into the agent configuration automatically. When specifying an application name, keep in mind that this value identifies the business application in the AppDynamics model of your environment to which this agent will report data. Conceptually, an AppDynamics business application does not necessarily correspond to the notion of an application in the monitored environment, where the application is usually thought of, for example, as a WAR file deployed to an application server. A single business application in AppDynamics may contain multiple applications in the monitored environment. For more information about modeling your environment in AppDynamics, see AppDynamics Concepts. Each monitored JVM must have a unique node name in AppDynamics. This means that you need to run the wizard for each JVM to monitor, or, after downloading the agent, edit the configuration file that specifies the agent naming properties, controller-info.xml, to at least change the node name value before copying it to other nodes.

Automatic Naming in a Self-Service Pro Trial

If you are using a self-service trial edition of AppDynamics Pro, AppDynamics names your application, tier, and node dynamically. AppDynamics uses the following naming scheme to identify agents that do not otherwise identify themselves in controller-info.xml or using startup arguments to the JVM: Application name: MyApp Tier name: MyTier

Copyright © AppDynamics 2012-2015 Page 4 Node name: @: (for example: [email protected]:8080) The automatically generated node name includes the port number that the server listens on. By using the listening port number in the node name, automatic naming ensures that when there are multiple instances of an application server on a single machine, all instances have unique node names.

Note that the port number used in the node name may not be the primary listening port for the server. If a server listens on multiple ports, automatic naming uses the lowest numbered port in the node name. For example, if a server uses port 8080 as a primary HTTP port but listens for shutdown requests on port 8005, the node will be named with the 8005 port. For tiers, the Controller automatically recognizes distinct logical tiers based on traffic flow between the nodes and associates the nodes to individual tiers accordingly. All tiers belong to a single business application, MyApp. As you learn more about how you want to organize your applications in AppDynamics, you can change the names of nodes, tiers, or business applications in the Controller UI or in the configuration.

Install the Agent on the App Server

After you download the agent, install it to your app server. The final window of the Agent Download Wizard includes brief instructions for installing the agent. 1. Log on as an administrator to the machine running your Java application. Unzip the AppServerAgent.zip file. For example, on Linux unzip the agent to home/appdynamics. This is the directory.

unzip AppServerAgent.zip -d /opt/appdynamics/appagent

2. Edit your startup configuration file to include the Java Agent. Show more information on startup scripts...

View Application Activity in the Controller

Now you're ready to restart your application and view data in the Controller UI: 1. Restart the JVM. 2. Apply load to your application. 3. Log on to the Controller to see your application in action.

The agent instruments the application code and reports metrics back to the Controller. From here, you can install more agents or you can begin monitoring your application environment.

Java Supported Environments

On this page: JVM Support JVM Language Frameworks Support Application Servers Message Oriented Middleware Support JDBC Drivers and Database Servers Support Business Transaction Error Detection NoSQL/Data Grids/Cache Servers Support Java Frameworks Support RPC/Web Services API Support Related pages: Supported Environments and Versions Rate this page:

Supported Platform Matrix for the Java Agent

This page documents known environments in which the Java Agent has been used to instrument applications. The Java Agent can target specific Java bytecode. This provides wide-ranging flexibility, so if an environment is not listed here, this does not preclude the Java Agent from being able to extract valuable performance metrics. Contact AppDynamics Support or Sales for additional details.

Copyright © AppDynamics 2012-2015 Page 6 Notes: A dash ("-") in a table cell indicates that this column is not relevant or not supported for that particular environment. In cases where no version is provided, assume that all versions are supported. Contact AppDynamics Support or Sales for confirmation. For environments that require additional configuration, a separate table describing or linking to configuration information follows the support matrix. For environments supported by AppDynamics End User Monitoring, see Supported Environments and Versions - Web EUM.

JVM Support The AppDynamics Java Agent supports applications running with a JRE or a full JDK. These are the known JVM environments in which the Java Agent has been used to instrument applications.

Vendor Implementation Version Operating Object Automatic Custom Memory Structures System Instance Leak Tracking Detection Content Access Inspection Tracking

Oracle Java HotSpot 7 Solaris - - - - Update Sparc 64, 45+ Windows, Linux

Oracle Java SE 81 Solaris Yes Yes Yes Yes (Standard Sparc 64, Edition) Windows, Linux

BEA JRockit 1.5 - - Yes Yes Yes

BEA JRockit 1.6, 1.7 - - Yes Yes -

Oracle JRockit JVM 28.1+ Linux Intel - - - - 64 Windows

IBM JVM 1.5.x, - - Yes, as Yes, as - 1.6.x, noted2 noted2,3 1.7.x

SUN JVM 1.5, - Yes Yes Yes Yes 1.6, 1.7

Open OpenJDK 1.6 Linux, - Yes - - Source windows, everywhere

Notes:

1 For examples of instrumenting new language constructs in Java SE 8, see Instrumenting Java 8 Constructs.

2 Object instance tracking, automatic leak detection, and custom memory structure monitoring are not supported with the IBM Java Agent on an IBM JVM. It's possible to work around this limitation by using the Java Agent for the Sun and JRockit JVM on an IBM JVM, but doing so can result in a negative performance impact.

3 For IBM JVMs, a restart is required after configuring the custom memory structure.

JVM Language Frameworks Support No additional configuration is required for these frameworks.

Vendor JVM Version Correlation/ Exit Transports Notes Language Entry Points Framework Points

Open Source / Akka Actor 2.1 - Yes Yes Netty Remoting exit/entry 2.3 supported. Typesafe Persistence Reactive (experimental Platform module in v2.3) is not currently supported.

Open Source Groovy - Yes Yes

Open Source / Play for 2.1 - Yes - HTTP Includes framework Scala 2.3 over Netty specific entry points Typesafe Reactive Platform

Open Source / Spray.io - No No No Currently not supported Typesafe Reactive Platform

Pivotal Grails - - - -

The Typesafe Reactive Platform is a JVM-based runtime and collection of tools used to build reacti ve applications. This includes Scala, Play, Akka, and Spray.io.

Application Servers These are the known application server environments in which the Java Agent has been used to

Copyright © AppDynamics 2012-2015 Page 8 instrument applications. Some require additional configuration. Click the link on the server or OSGi Runtime name in the following support matrix for information about additional configuration required or related configuration topics. Application servers are usually found by the Java Agent as an entry point.

Vendor Application Server / Version SOA RMI JMX Entry OSGi Runtime Protocol Supported Points

Apache Felix - - - - Yes

Apache Sling - - - - Yes

Apache Tomcat 5.x, - - Yes 6.x,7.x

Apache Resin 1.x - 4.x - - - -

Adobe Cold Fusion 8.x, 9.x - No - Yes

Equinox - - - - Yes

Eclipse Jetty 6.x, 7.x - - - -

IBM InfoSphere 8.x - - - Yes

IBM WebSphere 6.1 JAX-WS - - Yes

IBM WebSphere 7.x JAX-WS Yes, detect Yes for Yes and correlate WebSphere PMI

IBM WebSphere 8.x JAX-WS Yes, detect - Yes and correlate

Open Liferay Portal - - - - - Source

GlassFish Enterprise 2.x - - Yes Yes Server

Oracle GlassFish Server and 3.1+ - - Yes for Yes GlassFish Server AMX Open Source Edition

Oracle WebLogic Server 9.x+ JAX-WS Yes, detect Yes Yes and BEA and correlate for 10.x

Software webMethods 9.5, 9.6 - - - Yes AG

Application Server - - Yes, detect - Yes (OC4J) and correlate for 10.x

- Grails, with Tomcat - - - - 7.x, Glassfish v3, Weblogic 12.1.1 (12c)

- JBoss Server 4.x, 5.x - Yes, detect - Yes and correlate

JBoss AS/Wildfly 6.x, 7.x, Yes Yes 8.x

JBoss EAP 6.11, Yes Yes 6.2.0, 7.x

Application Server Configuration For application server environments that require additional configuration, this section provides some information and links to topics that help you configure the environment. Environments in the Application Server Support table that require additional configuration, link to the configuration table below.

Application Server Topics for Required and Optional Configuration

Apache Felix OSGi Infrastructure Configuration

Apache Sling OSGi Infrastructure Configuration

Apache Tomcat Apache Tomcat Startup Settings

Apache Resin Resin Startup Settings

Apache Cold Fusion Configuration is required for transaction discovery; see Servlet Entry Points

Equinox OSGi Infrastructure Configuration

Eclipse Jetty Jetty Startup Settings

IBM InfoSphere IBM WebSphere and InfoSphere Startup Settings

IBM WebSphere IBM WebSphere and InfoSphere Startup Settings

Copyright © AppDynamics 2012-2015 Page 10 Sun GlassFish Enterprise Server GlassFish JDBC connection pools can be manually configured using MBean attributes and custom JMX metrics GlassFish Startup Settings Modify GlassFish JVM Options

Oracle GlassFish Server (including GlassFish Startup Settings GlassFish Server Open Source Modify GlassFish JVM Options Edition)

Oracle and BEA WebLogic Server Oracle WebLogic Startup Settings

Software AG webMethods webMethods Startup Settings

Tibco ActiveMatrix BusinessWorks Tibco ActiveMatrix BusinessWorks Service Engine Service Engine Settings

JBoss Server JBoss and Wildfly Startup Settings

Message Oriented Middleware Support These are the known message oriented middleware environments in which the Java Agent has been used to instrument applications. Some require additional configuration. Click the link on the messaging server name in the following support matrix for information about additional configuration required or related configuration topics. Message oriented middleware servers are usually found by the Java Agent as an entry point.

Vendor Messaging Server Version Protocol Correlation/Entry Exit JMX Points Points

Apache ActiveMQ 5.x+ JMS 1.x Yes Yes Yes

Apache ActiveMQ 5.x+ STOMP No - Yes

Apache ActiveMQ 5.8.x+ AMQP 1.0 No - Yes

Apache ActiveMQ 5.x+ SOAP Yes - Yes

Apache Axis 1.x, 2.x JAX-WS Yes Yes -

Apache Apache CXF 2.1 JAX-WS Yes Yes -

Apache Synapse 2.1 HTTP Yes Yes -

Fiorano Fiorano MQ - - - -

IBM IBM MQ 6.x, 7.x - - - -

IBM IBM Web Application 6.1+, Embedded - Yes - Server (WAS) 7.x JMS

JBoss MQ 4.x - - - Yes

JBoss JBoss Messaging 5.x - - - Yes

JBoss HornetQ - - - - Yes

Open MQ - - - - -

Mulesoft Mule ESB 3.4 HTTP Yes Yes -

Oracle Jave Message Service 2.0 JMS correlation of the Yes listener is disabled by default

Oracle Oracle AQ - JMS - Yes -

Oracle / WebLogic 9.x+ JMS 1.1 Yes Yes Yes BEA

Progress SonicMQ - - - - -

Pivotal RabbitMQ - HTTP - Yes -

Rabbit RabbitMQ Spring Client - - Yes Yes -

Spring Spring Integration 2.2.0 JMS Yes Yes Yes

WSO2 Enterprise Service Bus 4.7 - Yes Yes - (ESB)

Message Oriented Middleware Configuration For message oriented middleware environments that require additional configuration, this section provides some information and links to topics that help you configure the environment. Environments in the Message Oriented Middleware Support table that require additional configuration, link to the configuration table below.

Messaging Server Topics for Required and Optional Configuration

Apache ActiveMQ JMS Message Queue Exit Points

Apache Axis Default exclude rules exist for Apache Axis, Axis2, and Axis Admin Servlets. See also, Web Service Entry Points

Apache Synapse To enable correlation, set node property enable-soap-header-correl ation=true.

IBM Web Application No additional configuration is required. See also, Server JMS Message Queue Exit Points

IBM WebSphere MQ IBM Websphere MQ Message Queue Exit Points

Mule ESB Mule ESB Startup Settings Mule ESB Support See also HTTP Exit Points for Java

BEA WebLogic Oracle WebLogic Startup Settings

Pivotal RabbitMQ No additional configuration is required. See also, RabbitMQ Message Queue Exit Points

RabbitMQ Spring No addition configuration is required, See also, Client Message Queue Exit Points for Java

Spring Integration Spring Integration Support See also, JMS Message Queue Exit Points

JDBC Drivers and Database Servers Support These are the known JDBC driver and database server environments in which the Java Agent has been used to instrument applications. AppDynamics can follow transactions using these drivers to the designated database.

JDBC Driver Version Driver Type Database Database Vendor Server Version

Apache 10.9.1.0 Embedded or client Derby -

Apache - - Cassandra -

Progress DataDirect data connectivity for ODBC and - - JBDC driver access, data integration, and SaaS and cloud computing solutions

IBM JDBC 3.0 version DB2 Universal JDBC driver DB2 9.x 3.57.82 or JDBC 4.0 version 4.7.85

IBM JDBC 3.0 version DB2 Universal JDBC driver DB2 10.1 3.66.46 or JDBC 4.0 version 4.16.53

Microsoft 4 Type II MS SQL 2012* Server

Oracle 5.x Type II, Type IV MySQL 5.x MySQL, MySQL Community

Open Connector/J Type IV MySQL 5.x Source 5.1.27

Open - Type IV Postgres 8.x, 9.x Source

Oracle 9.x Type II, Type IV Oracle 8i+ Database

Sybase jConnect Type IV Sybase -

Teradata Teradata -

Notes: Type II is a C or OCI driver Type IV is a thin database client and is a pure Java driver

Business Transaction Error Detection The Java Agent supports the following logging frameworks for business transaction error detection: Apache Log4j and Log4j 2 java.util.logging Simple Logging Facade for Java (SLF4J) Logback To instrument other types of loggers, see Configure a Custom Logger.

NoSQL/Data Grids/Cache Servers Support These are the known NoSQL, data grids and cache server environments in which the Java Agent has been used to instrument applications. Some require additional configuration. Click the link on the database, data grid or cache name in the following support matrix for information about additional configuration required or related configuration topics.

Vendor Database/Data Grid/Cache Version Correlation/Entry JMX Points

Apache Casandra (DataStax, REST) and 1.x Correlation Yes Cassandra CQL3

JBoss JBoss Cache TreeCache - - -

Terracotta EhCache - - -

Open Memcached - - - Source

Open MongoDB - - - Source

Oracle Coherence 3.7.1 Custom-Exit Yes

JBoss Infinispan 5.3.0+ Correlation -

NoSQL/Data Grids/Cache Servers Configuration For NoSQL, data grids, and cache server environments that require additional configuration, this section provides some information and links to topics that help you configure the environment. Environments in the NoSQL/Data Grids/Cache Servers Support table that require additional configuration, link to the configuration table below.

Database/Data Grid/Cache Topics for Required or Optional Configuration

Apache Cassandra (DataStax, REST) and Cassandra Exit Points for Java Cassandra CQL3 Apache Cassandra Startup Settings

Apache Lucene - Apache Solr Solr Startup Settings

JBoss JBoss Startup Settings

Terracotta EhCache EhCache Exit Points

Open Source Memcached Memcached Exit Points

Open Source MongoDB Configure Backend Detection for Java

Oracle Coherence Coherence Startup Settings

Java Frameworks Support These are the known Java framework environments in which the Java Agent has been used to instrument applications. Some require additional configuration. Click the link on the Java framework name in the following support matrix for information about additional configuration required or related configuration topics.

Vendor Framework Version SOA protocol Auto Entry Exit Detection (WebServices) Naming Points Points

Adobe ColdFusion 8.x, 9.x - - Yes - Configuration required for transaction discovery

Apache Cassandra - - - Yes Yes Apache Thrift with Thrift fr Entry and amework Exit points are detected

Apache Struts 1.x, 2.x - - Yes Struts Actions are detected as entry points, struts invocation handler is instrumented

Apache Tapestry 5 - - Yes - Not by default

Wicket - - No Yes - Not by default

Apple WebObjects 5.4.3 HTTP Yes Yes - Yes

CometD 2.6 HTTP Yes Yes - -

Eclipse RCP (Rich ------Client Platform)

Google Google 2.5.1 HTTP Yes Yes - - Web Toolkit (GWT)

JBoss JBossWS 4.x, 5.x Native Stack - - - - Native Stack

Open Direct Web ------Source Remoting (DWR)

Open Enterprise 2.x, 3.x - - Yes - - Source Java Beans (EJB)

Open Hibernate 1.x - - - - - Source JMS Listen ers

Open Java ------Source Abstract Windowing Toolkit (AWT)

Open Java Server 1.x - Yes Yes - Not by Source Faces (JSF) default

Open Java Server 2.x - Yes - - Yes Source Pages

Open Java 2.x - - - - - Source Servlet API

Open Jersey 1.x, 2.x REST, Yes Yes No Not by Source JAX-RS default

Open WebSocket 1.0 (Java EE - Yes, Yes, Yes Detection is Source 7, JSR-356) BT Naming correlation automatic not not configurable supported

Open AngularJS - - - Yes - - Source - Google

Oracle Coherence 2.x, 3.x - - - - - with Spring Beans

Oracle Swing (GUI) ------

Oracle WebCenter 10.0.2,10.3.0 - - - - -

Open JRuby - - - Yes - Not by Source HTTP default

Spring Spring MVC - - - Yes - Not by default

Java Frameworks Configuration For the Java framework environments that require additional configuration, this section provides some information and links to topics that help you configure the environment. Environments in the

Java Framework Topics for Required or Optional Configuration

Adobe BlazeDS Message Queue Exit Points for Java

Adobe ColdFusion Configuration is required for transaction discovery Java Web Application Entry Points Servlet Entry Points

Apache Cassandra with Thrift No additional configuration is required. framework

Apache Struts Struts Entry Points

Apache Tapestry Java Web Application Entry Points Servlet Entry Points

Wicket Java Web Application Entry Points Servlet Entry Points

Apple WebObjects Business transaction naming can be configured via getter-chains, see Getter Chains in Java Configurations Identify Transactions by POJO Method Invoked by a Servlet

CometD See also, HTTP Exit Points for Java

Open Source Enterprise Java EJB Entry Points Beans (EJB)

Open Source Hibernate JMS No additional configuration is required. See also, Listeners Advanced Options in Call Graphs

Open Source Java Server Java Web Application Entry Points and Servlet Entry Faces (JSF) Points

Open Source Java Server Servlet Entry Points Pages

Open Source Jersey JAX-RS Support and node properties: rest-num-segments rest-transaction rest-uri-segment-scheme See App Agent Node Properties Reference for information on the properties.

Open Source WebSocket Node property: websocket-entry-calls-enabled

Spring MVC Java Web Application Entry Points Servlet Entry Points

RPC/Web Services API Support These are the known Java framework environments in which the Java Agent has been used to instrument applications. Some require additional configuration. Click the link on the RPC, web services or API framework name in the following support matrix for information about additional configuration required or related configuration topics.

Vendor RPC/Web Version SOA Auto Correlation/Entry Exit Configurable Services Protocol- Naming Points Points BT Naming API WebServices Properties Framework

Apache Apache 2.1 JAX-WS Yes Yes Yes Yes CXF

Apache Apache - HTTP Client Yes Yes Yes - Commons

Apache Apache - - Yes Yes Yes Yes Thrift

IBM WebSphere 6.x JAX-RPC - - - -

IBM WebSphere 7.x, 8.x JAX-RPC - - - -

IBM Websphere 7.x, 8.x IIOP - - - -

JBoss JBoss 4.x, 5.x RMI Yes Yes Yes Yes

Open java.net.Http - HTTP Yes - Yes Yes Source

Open HTTPClient 0.3-3 Oracle SOA - Correlation: Yes; Yes - Source (and Entry: No potentially others that embed this library)

Oracle GlassFish - JAX-WS - - - - Metro

Oracle Oracle ORMI - no - - - Application Server

Oracle WebLogic 10.x T3, IIOP Yes Correlation: Yes; Yes - Entry: No

Oracle WebLogic 9.x, JAX-RPC - - - - 10.x

Sun Sun RMI - IIOP - Not by Default - -

Sun Sun RMI - JRMP - By Default Yes host/port

- Web - SOAP over - Yes Yes - Services HTTP

RPC/Web Services API Framework Configuration For the RPC and web service API environment that require additional configuration, this section provides some information and links to topics that help you configure the environment. Environments in the RPC/Web Services API Framework Support table that require additional configuration, link to the configuration table below.

RPC/Web Services Topics for Required or Optional Configuration API

Apache Commons HTTP Exit Points for Java

Apache Thrift Binary Remoting Entry Points for Apache Thrift

IBM WebSphere IBM WebSphere and InfoSphere Startup Settings, Instrument JVMs in a Dynamic Environment. See also, Default configuration excludes WebSphere classes.

JBoss JBoss and Wildfly Startup Settings

Open HTTP Exit Points for Java Source java.net.Http

Oracle WebLogic Oracle WebLogic Startup Settings Default configuration excludes WebLogic classes

Web Services Create Match Rules for Web Services Web Service Entry Points Web Services Exit Points for Java

On this page: Planning for Java Agent Installation Java Agent Resource Overhead Download and Unzip the Java Agent Agent Configuration Options and Precedence Configure the Java Agent Connection to the Controller Configure Java Agent Account Information (Multi-tenant mode or SaaS Installations Only) Configure the Business Application, Tier, and Node Add the Java Agent as a javaagent Argument to the JVM Attach the Java Agent to a Running JVM Process Verify Installation Additional Installation Scenarios Related pages: Java Agent Configuration Properties Rate this page:

Installing the AppDynamics Java Agent requires putting the agent software on the application machine, configuring the agent settings, and adding the Java Agent to the JVM. You add the agent to the JVM by including it as a argument in the startup script for the JVM. To avoid permission issues, you should install the agent as the same user that owns the JVM or as an administrator on the host machine. In any case, the user that runs the JVM must have write privileges to the conf and logs directories in the Java Agent home. While it's possible for the Java Agent to run on the same JVM as other Byte Code Injection (BCI) agents as long as the other agents do not interfere with the Java Agent class transformation, AppDynamics advises against it. As always, you should thoroughly test your deployment in a staging environment to detect possible conflicts.

Planning for Java Agent Installation

Before installing the Java Agent, be prepared with the following information.

Planning Item Description

Copyright © AppDynamics 2012-2015 Page 21 Where is the startup This is where you can add startup arguments in the script file and script for the JVM? system properties, if needed. If using a Java service wrapper, you need to know the location of the wrapper configuration.

What host and port is the For SaaS customers, AppDynamics provides this information to Controller running on? you. For on-premise Controllers, this information is configured during Controller installation. See (Install the Controller or Configur e Windows for Controller Hosting).

To what AppDynamic Usually, all JVMs in your distributed application infrastructure business application does belong to the same AppDynamics business application. You assign this JVM belong? a name to the business application. For details see AppDynamics Concepts.

To what AppDynamics You assign a name to the tier. For details see AppDynamics tier does this JVM Concepts. belong?

In addition to the JVM startup script file, two other files are important during installation: javaagent.jar is the agent binary file. The -javaagent argument should specify the fully-qualified path to this file. No separate classpath arguments need to be added. controller-info.xml under /ver/conf is where you add the configuration mentioned in the planning list. This file contains configuration settings specific to the agent version you are using, and take precedence over the same file in the < agent_home>/conf directory. For most settings you should use this version-specific file. The following sections take you through the steps for downloading and installing the Java Agent manually. Alternatively, configure the agent using Agent Download Wizard, as described in Instru ment Java Applications.

Java Agent Resource Overhead

While relatively lightweight, the Java Agent does add a certain amount of overhead to the overall resource consumption of an application. The existing resource allocation for most applications can absorb the additional overhead imposed by the agent, so you do not normally need to increase the resource allocation for the application when installing the agent. However, the exact CPU or memory overhead added by the agent can vary depending upon your application and how you have configured AppDynamics. If your application operates within a small margin of its existing memory resource allocation, you may choose to increase the allocation for the application. AppDynamics recommends allocating the following amounts of additional Heap and PermGen space to accommodate the agent:

Copyright © AppDynamics 2012-2015 Page 22 Maximum heap size (-Xmx): 100 MB in addition to the amount required by the application Maximum PermGen (permanent generation) heap size (-XX:MaxPermSize): 20 MB in addition to the amount required by the application In terms of CPU consumption, the agent can add between 0% to 2% additional overhead on CPU usage. Certain resource-intensive AppDynamics features, such as asynchronous transaction tracking, can increase resource consumption as well. AppDynamics recommends that you monitor the memory consumption of your application to ensure that there are sufficient resources allocated to it.

Download and Unzip the Java Agent

1. Download the Java Agent ZIP file from AppDynamics Download Center. 2. Extract the ZIP file to the destination directory as the same user or administrator of the JVM. Take note of the following:

Extract the Java Agent to a directory that is outside of your container All files should be readable by the Java Agent Runtime directory should be writable by the Java Agent Note: Be sure to avoid installing the agent into a directory used by the application server, such as to the Tomcat webapps directory. To avoid this possibility, install the Java Agent to a directory outside of application server home directory, such as to \usr\local\agentsetup\appserveragent.

Agent Configuration Options and Precedence

You can configure the Java app agent settings, such as its Controller connection settings, using one of several mechanisms. Those mechanisms and the order of priority (in the case of conflicting settings) are: 1. Environment variable 2. System property 3. /ver/conf/controller-info.xml When reading its configuration, the agent checks each of these sources in the order shown and uses the value from the first source that contains a non-empty value for a particular setting. If you used the download Wizard in the UI to get the agent, you can find the settings in the version specific controller-info.xml file.

Configure the Java Agent Connection to the Controller

Configure properties for the Controller host name and its port number.

Configure in Configure using System Required Default controller-info.xml Properties

-Dappdynamics.controller.port Yes For On-premise Controller installations: By default, port 8090 is used for HTTP and 8181 is used for HTTPS communication. For SaaS Controller service: By default, port 80 is used for HTTP and 443 is used for HTTPS communication.

Optional settings for Java Agent-to-Controller communication To configure the Java Agent to use SSL, see Java Agent Configuration Properties and Enable SSL (Java). To configure the Java Agent to use proxy settings see Java Agent Configuration Properties

Configure Java Agent Account Information (Multi-tenant mode or SaaS Installations Only)

This step is required only when the AppDynamics Controller is configured in Controller Tenant Mode or when you use a SaaS Controller. Skip this step if you are using single-tenant mode, which is the default in an on-premise installation. Specify the properties for Account Name and Account Key. This information is provided in the Welcome email from the AppDynamics Support Team. You can also find this information in the /initial_account_access_info.txt file.

Configure using Configure using Required Default controller-info.xml System Properties

Dappdynamics.agent.accountName Required only if None. your Controller is configured for mul ti-tenant mode or your controller is hosted.

Configure the Business Application, Tier, and Node

When configuring a Java Agent, you identify the business application, tier, and node it belongs to in the AppDynamics application model. See AppDynamics Concepts and Name Business Applications, Tiers, and Nodes for more information on this model. You can configure these properties using either the controller-info.xml file or JVM startup script options. Use these guidelines when configuring agents: Configure items that are common for all the nodes in the controller-info.xml file. Configure information that is unique to a node in the startup script.

Configure using Configure using Required Default controller-info.xml System Properties

Dappdynamics.agent.applicationName Yes, unless you use None automatic naming

Dappdynamics.agent.tierName Yes, unless you use None automatic naming

Dappdynamics.agent.nodeName Yes, unless you use None automatic naming

Your controller-info.xml file should now have values shown in the following sample configuration file:

192.168.1.20 8090 ACMEOnline InventoryTier Inventory1

Automatic Naming for Application, Tier, and Node For a self-service trial edition of AppDynamics Pro, the Agent Download Wizard doesn't prompt you for the application, tier or node name. It uses a default naming scheme instead (described in I nstrument Java Applications). You can use automatic naming with a standard edition of AppDynamics Pro by adding the

true

Add the Java Agent as a javaagent Argument to the JVM

Add the Java Agent binary to the monitored process by adding a javaagent argument with the location of the Java Agent JAR file to the start-up script of the JVM:

-javaagent:/javaagent.jar

Installing the agent with the javaagent argument requires a restart of the JVM. If it's not possible or convenient to restart the JVM when performing the configuration, you can attach the agent to the running process, as described in the following section. Use the server-specific instructions below to add this argument for different application server JVMs: Java Server-Specific Installation Settings Java Agent Configuration Properties Use System Properties for Java Agent Settings Use Environment Variables for Java Agent Settings Instrument Multiple JVMs on a Single Machine Instrument Dynamically Identified JVMs Instrument JVMs in a Dynamic Environment Instrument JVMs Started by Batch or Cron Jobs Instrument JVMs in Restricted Environments Automate Java Agent Deployment Instrument Apple WebObjects Applications

Attach the Java Agent to a Running JVM Process

Attaching the agent to a running JVM allows you to install the Java Agent without requiring a JVM restart. This approach would normally be used alongside adding the -javaagent argument to the JVM startup script or some other persistent approach, to ensure that the agent is loaded again at the next JVM restart. However, dynamic attachment allows you to install the agent when restarting the JVM is not possible or convenient. Dynamic agent attachment works if: The JVM is version 1.6 or later. The JVM is an Oracle (HotSpot) JVMs (unavailable for IBM or JRockit JVMs). A few other points to consider are: Do not attach the agent dynamically to an environment that is already instrumented (either by the AppDynamics Java Agent or another type other agent). Doing so can cause

Copyright © AppDynamics 2012-2015 Page 26 unforeseeable issues and errors. Attaching the AppDynamics Java Agent to a running environment will impact the performance of the application while the agent performs the class retransformation needed to instrument the application. The agent overhead will return to its normal operating level wh en it finishes the process, but it is important to consider the potential performance impact to production services. To attach the agent to the JVM, follow these steps: 1. Determine the PID of the JVM to which you want to attach. For example, on Linux, use:

ps -A | grep java

On Windows, use:

jps -l

2. Run the following command, replacing the placeholders for the path to the tools.jar file in your JDK, path to the AppDynamics Java Agent home directory, and the JVM process ID with values appropriate for your environment:

java -Xbootclasspath/a:/lib/tools.jar -jar //javaagent.jar

Use the equivalent paths for Windows, including drive letter.

The following shows an example with system output included:

[appduser@my_centos6 ~]$ ps -A | grep java 6780 pts/1 00:00:04 java [appduser@my_centos6 ~]$ java -Xbootclasspath/a:/usr/java/jdk1.7.0_79/lib/tools.jar -jar /home/appduser/appagent/javaagent.jar 6780 Attaching to VM [6780] agent path >>>/home/appduser/appagent/javaagent.jar

Verify Installation

After a successful install, your agent logs, located at /logs, should contain the following message:

Started AppDynamics Java Agent Successfully

Copyright © AppDynamics 2012-2015 Page 27 If the agent log file is not present, the Java Agent may not be accessing the javaagent command properties. To troubleshoot, check the application server log file where STDOUT is logged. It will have the fallback log messages, useful for troubleshooting the agent. Also, verify that the agent is able to connect to the Controller in the Controller UI. To verify, log in to the Controller UI and click the Settings cog icon at the top right of the screen, and then AppDyn amics Agents. In the list, look for the agent in the list by machine hostname.

Additional Installation Scenarios

Refer to the links below for typical installation scenarios, especially for cases where there are multiple JVMs on the same machine: Instrument Multiple JVMs on a Single Machine Use System Properties for Java Agent Settings Instrument JVMs in a Dynamic Environment Instrument JVMs Started by Batch or Cron Jobs

Java Server-Specific Installation Settings

The following pages describe individual considerations and instructions for installing the Java Agent for some of the application servers supported for the Java Agent. Apache Cassandra Startup Settings Apache Tomcat Startup Settings Coherence Startup Settings GlassFish Startup Settings IBM WebSphere and InfoSphere Startup Settings JBoss and Wildfly Startup Settings Jetty Startup Settings Mule ESB Startup Settings Oracle WebLogic Startup Settings OSGi Infrastructure Configuration Resin Startup Settings Solr Startup Settings Standalone JVM Startup Settings Tanuki Service Wrapper Settings Tibco ActiveMatrix BusinessWorks Service Engine Settings webMethods Startup Settings

Apache Cassandra Startup Settings

On this page: Instrument Cassandra in a Windows Environment Instrument Cassandra in a Linux Environment

The Java Agent bootstraps using the javaagent command line option. Add this option to the cassandra (Linux) or cassandra.bat (Windows) file.

Instrument Cassandra in a Windows Environment

1. Open the apache-cassandra-x.x.x\bin\cassandra.bat file. 2. Add the Java Agent javaagent path to the JAVA_OPTS variable. Make sure to include the drive in the full path to the Java Agent directory.

-javaagent:\javaagent.jar

For example:

set JAVA_OPTS=-ea -javaagent:C:\appdynamics\agent\javaagent.jar -javaagent:"%CASSANDRA_HOME%\lib\jamm-0.2.5.jar . . .

3. Restart the Cassandra server. The Cassandra server must be restarted for the changes to take effect.

Instrument Cassandra in a Linux Environment

1. Open the apache-cassandra-x.x.x/bin/cassandra.in.sh file. 2. Add the javaagent argument at the top of the file:

JVM_OPTS=-javaagent:/javaagent.jar

For example:

JVM_OPTS=-javaagent:/home/software/appdynamics/agent/javaagent.jar

3. Restart the Cassandra server for the changes to take effect.

Apache Tomcat Startup Settings

On this page: Configure the HTTP Header Maximum Size Configure Tomcat in a Linux Environment Configure Tomcat in a Windows Environment Configure Tomcat as a Windows Service

To instrument applications on Apache Tomcat, you need to install the Java Agent and verify the default maximum HTTP header size in the Tomcat configuration, as described in the following section.

Configure the HTTP Header Maximum Size By default, the maximum HTTP header size for Tomcat is 8 KB. To accommodate the custom HTTP header that AppDynamics adds to enable distributed transaction correlation, you need to increase the default maximum HTTP header size. It is recommended that you set the value of the attribute to at least 24576 (24 KB). You can increase the size using a Tomcat configuration property in /conf/server.xml. The maximum permitted header length is controlled by the maxH ttpHeaderSize HTTP attribute.

Configure Tomcat in a Linux Environment

1. Open the catalina.sh file located at /bin. 2. Add the -javaagent argument to the Catalina environment variables. You can put this command anywhere in the file before the command execution portion of the script.

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/javaagent.jar"

Replace with the full path to the Java Agent JAR file.

For example:

3. Increase the default maximum HTTP header size configuration, if necessary. See Configure the HTTP Header Maximum Size. 4. Restart the application server. The application server must be restarted for the changes to take effect.

Configure Tomcat in a Windows Environment

1. Open the catalina.bat file, located at \bin. 2. Add the following command to set the environment for Catalina anywhere in the file before the command execution portion of the script.

set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:"Drive:\javaagent.jar"

Replace with the fully qualified path to the Java Agent JAR file.

For example:

Configure Tomcat as a Windows Service When running Tomcat as a Windows service, add the javaagent argument to your Tomcat startup properties. These instructions apply to Apache Tomcat 6.x or later versions.

To install the Java agent in Tomcat running as a Windows service

1. Ensure that you are using administrator privileges. 2. Click Programs -> Apache Tomcat. 3. Run Configure Tomcat. 4. Click the Java tab. 5. In the Java Options add:

-javaagent:"\javaagent.jar"

For example:

6. Increase the default maximum HTTP header size configuration, if necessary. See Configure the HTTP Header Maximum Size. 7. Restart the Tomcat service to have the changes take effect.

Coherence Startup Settings

To add the javaagent command in Oracle Coherence: 1. In the /bin/cache-server.sh file, update the following:

$JAVAEXEC -server -showversion $JAVA_OPTS -javaagent:/javaagent.jar -cp "$COHERENCE_HOME/lib/coherence.jar" com.tangosol.net.DefaultCacheServer $1

2. Restart the application server to have the changes take effect.

GlassFish Startup Settings

On this page: Instrument GlassFish 3.0 Instrument GlassFish 3.1 Verify the Configuration

Rate this page:

The Java Agent bootstraps using the javaagent command line option.

Instrument GlassFish 3.0

1. Configure the OSGi containers. For details see OSGi Infrastructure Configuration. 2. Log into the GlassFish domain where you want to install the Java Agent. 3. In the left navigation tree Common Tasks section, click Application Server. The Application Server Settings dialog opens. 4. In the JVM Settings tab, click JVM Options. 5. Click Add JVM Option and add an entry for the javaagent argument. The javaagent argument contains the full path, including the drive, of the agent home directory.

-javaagent::\\javaagent.jar

6. Restart the application server. The application server must be restarted for the changes to take effect.

Instrument GlassFish 3.1

1. If you are using GlassFish v3.1, first configure the OSGi containers. For details see OSGi Infrastructure Configuration. 2. Log into the GlassFish domain where you want to install the Java Agent. Note: Remember to turn on remote administration by entering the following command from the /appserver/glassfish/bin directory:

asadmin enable-secure-admin

3. In the Configurations section in the left navigation tree, click server-config and then click J VM Settings. 4. On the JVM Settings tab, click JVM Options. 5.

-javaagent::\javaagent.jar

For Linux:

-javaagent:/javaagent.jar

6. Restart the application server. The application server must be restarted for the changes to take effect.

Verify the Configuration To verify this configuration, look at the domain.xml file located at \domains\. The domain.xml file should have an entry as shown in the following screenshot.

About Glassfish AMX Support

Copyright © AppDynamics 2012-2015 Page 36 AppDynamics supports Glassfish AMX MBeans. Set the boot-amx node property to enable AMX MBeans. See boot-amx. You will see the AMX domain in the MBean Browser in the JMX tab of the node dashboard.

IBM WebSphere and InfoSphere Startup Settings

On this page: Instrument WebSphere 7.x or InfoSphere 8.x Instrument WebSphere 6.x Instrument WebSphere 5.x Verifying the Java Agent Configuration Security Requirements Running WebSphere with Security Enabled Instrument WebSphere in z/OS or Mainframe Environments

Rate this page:

The Java Agent bootstraps using the javaagent command line option.

Instrument WebSphere 7.x or InfoSphere 8.x

1. Log in to the Administrator console of the WebSphere node where you want to install the App Server Agent. 2. In the Administration Console click Servers. 3. Expand Server Type and click WebSphere application servers. 4. Click the name of your server. 5. Expand Java and Process Management and click Process Definition. 6. Under the Additional Properties section, click Java Virtual Machine. 7. Enter the javaagent option with the full path to the AppDynamics javaagent.jar file in the Generic JVM arguments field. For Windows:

-javaagent::\javaagent.jar

For Linux:

-javaagent:/javaagent.jar

8. Click OK.

Copyright © AppDynamics 2012-2015 Page 37 May require OSGI bootdelegation Websphere uses Equinox as its OSGi container. In some cases you may also need to add the Java agent packages to the OSGi bootdelegation system property as follows:

-Dorg.osgi.framework.bootdelegation=META-INF.services,com.singularity.*,c om.ibm.*

Instrument WebSphere 6.x

1. Log in to the Administrator console of the WebSphere node where you want to install the Java Agent. 2. In the left navigation tree, click Servers -> Application servers. 3. Click the name of your server in the list of servers.

4. In the Configuration tab, click Java and Process Management.

5. Enter the javaagent option with the full path to the Java Agentjavaagent.jar file in the Generic JVM arguments field. For Windows:

-javaagent::\javaagent.jar

For Linux:

-javaagent:/javaagent.jar

6. Click OK.

1. Log in to the Administrator console of the WebSphere node where you want to install the App Server Agent. 2. In the Administrative Console, click Servers. 3. Click Application Servers. 4. Click the name of your server. 5. Under Additional Properties, click Process Definition. 6. On the next page, under Additional Properties, click Java Virtual Machine. 7. Enter the javaagent option with the full path to the Java Agent javaagent.jar file in the Generic JVM arguments field.

For Windows:

-javaagent::\javaagent.jar

For Linux:

-javaagent:/javaagent.jar

Verifying the Java Agent Configuration Verify the configuration settings by checking the server.xml file of the WebSphere node where you installed the Java Agent. The server.xml file should have this entry:

Security Requirements Full permissions are required for the agent to function correctly with WebSphere. Grant all permissions on both the server level and the profile level.

Running WebSphere with Security Enabled If you want to run WebSphere while J2EE security or Global security is enabled, you need to make changes to WebSphere's server.policy file to prevent problems within the interaction between WebSphere and the Java Agent. Make the change listed below to the server.policy file, which is located in /properties or in /properties. Add the following block to the WebSphere server.policy file:

grant codeBase "file:\* AGENT_DEPLOYMENT_DIRECTORY \*/-" { permission java.security.AllPermission; };

Instrument WebSphere in z/OS or Mainframe Environments See Instrument JVMs in a Dynamic Environment.

JBoss and Wildfly Startup Settings

On this page: Quick Install Startup Argument Configuration Considerations Adding the Java Agent to JBoss in Standalone Mode Adding the Java Agent to JBoss in Domain Mode Making the LogManager Location Dynamic Troubleshooting

Rate this page:

Instrumenting JBoss applications with the AppDynamics agent requires adding up to three items of

Location of the Java Agent AppDynamics package names JBoss log manager package name and JAR location For most deployments (that is, those using a recent version of JBoss and the AppDynamics Java Agent) all three items are required. The following section takes you through the steps for configuring these items in such cases.

Quick Install If using a recent version of JBoss (AS 7.x or EAP 6.x or later) and running in standalone mode, you can instrument JBoss with the AppDynamics Java agent by adding the three startup options to the startup script for your JBoss instance, typically standalone.sh. For older versions of JBoss or if running in domain mode, be sure to verify the settings you need by reading the Startup Argument Configuration Considerations section.

To instrument JBoss with the Java Agent:

1. Add the -javaagent argument and set its value to the full path to the Java agent on your

system. (See callout in the figure below.) 2. Add the AppDynamics package names, appdynamics, appdynamics., com.singulari ty, and com.singularity. to the existing -Djboss.modules.system.pkgs property

(callout ). 3. Add the argument -Djava.util.logging.manager with the LogManager package name and add -Xbootclasspath argument, replacing its value with the path to the JBoss log

manager JAR file for your instance (callout ). 4. Restart the JVM. The following figure shows a sample JBoss startup script (standalone.sh) with the three options:

For the installation instructions in greater detail, see Adding the Java Agent to JBoss in Standalone Mode or Adding the Java Agent to JBoss in Domain Mode.

Startup Argument Configuration Considerations

Callout Option When needed?

Location of the Java Agent Always

AppDynamics packages as system If using an OSGi-compliant version of packages JBoss, including: AS 7.x+ EAP 6.x+

Log manager settings, which include: If using: Location of the log manager JAR file AppDynamics Agent version 3.9 or (as a -Xbootclasspath argument) later Package name for the log manager An IBM JVM (org.jboss.logmanager.LogManager) A Sun JVM with Remote JMX (note added as a system package that this requirement is not related to the AppDynamics Java Agent)

The Quick Install section describes how to configure the settings in the standalone startup script. But the exact file where you configure the settings depends on the operating mode of JBoss, its version, and even practices that are specific for your organization and environment. The following sections describes some of the considerations for where to configure the settings.

Standalone mode For standalone: In Linux, add the settings to standalone.conf or standalone.sh. In Windows, add the settings to standalone.conf.bat. If using JBoss 4.x or 5.x, add the configuration to run.sh for Linux or run.bat for Windows. For an example of this configuration, see Adding the Java Agent to JBoss in Standalone Mode.

Domain mode For domain mode, the location in which you need to configure the settings depends upon the nature of your environment. Keep in mind that a domain is made up of: A domain controller, which is the administration and configuration server for the JBoss environment. The domain.xml configuration file is the global configuration for the managed hosts. Host controllers, which manage a particular host with one or more application server nodes. There can be any number of host controllers and nodes. The hosts.xml file contains settings for the nodes on that host machine.

If the values of the settings you need to configure are the same for all hosts in the managed domain, you can put them in the domain.xml file for the Domain Controller. On the other hand, if the setting values vary among the hosts (for example, if the path to the log manager file varies between hosts), they should go into the settings in the host.xml file. Changes to the domain.xml require a restart of the management host. They are not propagated to the server hosts until they are restarted as well. The configuration settings can be split between domain.xml and host.xml, if you want to specify some settings globally and others by host. For an example of this configuration, see Adding the Java Agent to JBoss in Domain Mode.

Adding the Java Agent to JBoss in Standalone Mode The following procedures walk you through the steps for adding the agent to JBoss AS 7.x on Linux. These steps should work for OSGi-compliant versions of JBoss. However, note that your own environment may have specific considerations not covered here, for example, if you have existing, site-specific customizations to the JBoss startup configuration files. 1. Open the bin/standalone.conf file. 2. Search for the following line in standalone.conf.

JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman"

3. Add the com.singularity and org.jboss.logmanager packages to that line as follows:

JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman,com.singularity,org.jboss.log manager"

4. Add the following to the end of the standalone.conf file in the JAVA_OPTS section.

-Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:/jboss-logmanager-.ja r

Replace and with the path and log manager JAR filename for your system. See Making the LogManager Location Dynamic for information on making the path dynamic. 5. In the standalone.sh file, add the following javaagent argument.

export JAVA_OPTS="$JAVA_OPTS -javaagent:/agent_install_dir/javaagent.jar"

Put the argument above the following section of standalone.sh

... while true;do if [ "x$LAUNCH_JBOSS_IN_BACKGROUND" = "X" ]; then # Execute the JVM in the foreground eval \"$JAVA\" -D\"[Standalone]\"$JAVA_OPTS \ \"-Dorg.jboss.boot.log.file=$JBOSS_LOG_DIR/boot.log\" \ \"-Dlogging.configuration=file:$JBOSS_CONFIG_DIR/logging.properties\" \ -jar \"$JBOSS_HOME/jboss-modules.jar\" \

6. Restart the application server.

Adding the Java Agent to JBoss in Domain Mode The following steps walk you through the configuration for a JBoss installation running in domain mode. For this type of deployment: If all the server instances in the server group are part of the same business application, then configure -Dappdynamics.agent.applicationName in domain.xml; otherwise, configure the application name in the host.xml file for each specific server.

The -Dappdynamics.agent.applicationName argument specifies the name of the Business Application to use for the data reported by this Java Agent to the AppDynamics Controller. If all the server instances in the server group are part of the same tier then configure -Dapp dynamics.agent.tierName in domain.xml, otherwise configure the tier name in host.xml for each specific server.

The -Dappdynamics.agent.tierName argument specifies the name of the tier to use for the data reported by this Java Agent to the AppDynamics Controller. Edit the JBoss domain.xml and host.xml files as indicated in the following sections and then restart the application server.

1. Locate and edit domain.xml for the domain. This is usually located under $JBOSS_HOME/domain/configuration/. 2. Find the the system-properties element and add a property named jboss.modules.s ystem.pkgs with a value of com.singularity to the existing system properties. For example:

This property tells the JBoss class loader to load the AppDynamics packages. This is required for the Java Agent to run. 3. Under the server group name where you want to enable your agents, add the JVM options using the appropriate values for your agent location, JBoss application name, and tier name.

Modify the Host.xml file Add the -Dappdynamics.agent.nodeName JVM option in host.xml file (usually located under $JBOSS_HOME/domain/configuration/). This option tells the Java Agent the node name to use to connect to the AppDynamics Controller. Use the appropriate values for your node names. For example:

Making the LogManager Location Dynamic On standalone JBoss instances, instead of hard coding the path and name of the log manager JAR, you can use glob pattern matching techniques to make the path to the log manager file that you specify in the startup options more resilient to changes.

Windows In Windows, the standalone.conf.bat gets this additional snippet:

rem java.util.logging set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.jboss.logmanager.LogManager

rem bootclasspath set LOGMANAGER= for /f %%i in ('dir /b "%JBOSS_HOME%\modules\system\layers\base\org\jboss\logmanager\main\j boss-logmanager-*.jar"') do ( set LOGMANAGER_JAR=%JBOSS_HOME%\modules\system\layers\base\org\jboss\log manager\main\%%i ) set JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:%LOGMANAGER_JAR%

The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly.

Linux In Linux, you can populate the path dynamically with the following code:

JBOSS_MODULES_SYSTEM_PKGS ="org.jboss.byteman,com.singularity,org.jboss.logmanager"

JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.manager=org.jboss.logmanager.LogManager" JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:$(ls ${JBOSS_HOME}/modules/system/layers/base/org/jboss/logmanager/main/j boss-logmanager-*.jar)"

If using the ${JBOSS_HOME} variable, as in the example, be sure to set the variable to the directory to the JBoss installation directory on your system. The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly.

Troubleshooting The following sections contain information that may assist you in getting the Java Agent installed on JBoss.

Copyright © AppDynamics 2012-2015 Page 48 Verify JBoss startup arguments Most issues with installing the Java Agent on JBoss are attributable to conflicts between startup arguments. Settings you add for the Java Agent may be overridden or otherwise conflict with existing arguments in ways that are not always easy to detect. The best way to begin troubleshoot such startup issues is to print and inspect the startup arguments that JBoss actually gets when attempting to start. To do this, view JBoss process information during startup using the following command. Note that this command needs to be performed while the start up attempt is occurring, and before it fails.

ps -ef | grep [o]rg.jbossas | tr ' ' '\n' | sed -e '/^$/d'

Fix Linkage Error If you see this error:

Caused by: java.lang.LinkageError: loader constraint violation in interface itable initialization: when resolving method "com.microsoft.sqlserver.jdbc.SQLServerXAConnection.getXAResource()Ljavax/transa ction/xa/XAResource;" the class loader (instance of org/jboss/modules/ModuleClassLoader) of the current class, com/microsoft/sqlserver/jdbc/SQLServerXAConnection, and the class loader (instance of ) for interface javax/sql/XAConnection have different Class objects for the type javax/transaction/xa/XAResource used in the signature

Add the following JVM option to the startup script and restart the server:

-Dappdynamics.bciengine.class.lookahead=!*

The error indicates a race condition while loading classes. The flag controls the class loading hierarchy, thus preventing class loading problems.

JMXRegistrationAdvice callback error for target context ServiceBindingManager The following error at JBoss start up has been encountered in JBoss 6.x:

Copyright © AppDynamics 2012-2015 Page 49 14:06:58,531 ERROR [AbstractKernelController] Error installing to Configured: name=ServiceBindingManager state=Configured: java.lang.Exception: Error calling callback JMXRegistrationAdvice for target context ServiceBindingManager at org.jboss.dependency.plugins.AbstractLifecycleCallbackItem.install(AbstractLifec ycleCallbackItem.java:91) at org.jboss.dependency.plugins.AbstractController.handleLifecycleCallbacks(Abstrac tController.java:1830) at ...

If you encounter this error, edit the JBoss startup script run.conf (Linux) or run.conf.bat (Windows) and add the following properties as Java options (JAVA_OPTS):

-Djboss.platform.mbeanserver -Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilde rImpl

Jetty Startup Settings

On this page: Instrument Jetty Version 8.x or 9.x Instrument Jetty Version 6.x or 7.x

Rate this page:

The details for instrumenting the Jetty web server with the AppDynamics Java agent vary depending on the version of Jetty you are using, as described below.

Instrument Jetty Version 8.x or 9.x You can instrument Jetty with the AppDynamics agent either from the server startup command or by editing the Jetty startup configuration file. To add the agent to Jetty at the command line, pass the javaagent argument with the fully qualified location of the Java agent JAR file when starting the Jetty server. For example:

java -javaagent://javaagent.jar -jar start.jar

To use the startup configuration file, edit the start.ini file in the Jetty base directory by adding the following lines:

Be sure to specify the location of the AppDynamics javaagent.jar file in the javaagent argument as appropriate for your system. Restart the Jetty server after modifying the configuration file to have your changes take effect.

Instrument Jetty Version 6.x or 7.x For Jetty version 6.x or 7.x, you can add the javaagent command line option to your jetty.sh file, as follows: 1. Open the jetty.sh start script file. 2. Add the following javaagent argument to the beginning of the script.

java -javaagent://javaagent.jar

3. Save the script file. 4. Restart the application server for the changes to take effect.

Mule ESB Startup Settings

On this page: Configuring the Tanuki Service Wrapper Related pages: Mule ESB Support Rate this page:

To load the Java Agent in Mule ESB, pass the Java Agent JAR location as a JVM argument to Mule. Mule ESB 3.X or later uses the Tanuki configuration environment. To specify JVM arguments in your Mule ESB environment, you need to configure them as additional parameters to the Tanuki Java Service Wrapper configuration file, wrapper.conf, as described below.

Configuring the Tanuki Service Wrapper

1. Open the Java Service Wrapper configuration file: /conf/wrapper.conf 2. Find the location indicated for Java Additional Parameters:

# Java Additional Parameters wrapper.java.additional.1=

3. Add the path to the Java Agent JAR file as a JVM argument using a wrapper.java.additional. n parameter, as follows.

wrapper.java.additional.n="-javaagent:/path_to_appagent/javaagent.jar" wrapper.java.additional.n.stripquotes=TRUE

Where "n" is the next available integer among the wrapper.java.additional parameters already in the wrapper.conf file, if any. The numbers serve to identify each Java Additional Parameter in the file. Do not skip numbers when adding the property. Replace path_to_appagent to the path to the javaagent.jar file in your system. The stripquotes parameter is necessary only if there are spaces in the path or filename, but is safe to include if not.

For example, on a Linux system and with seven Java parameters already in the file, add the following properties:

wrapper.java.additional.8="-javaagent:/opt/AppDynamics/Agent/app_agent/jav aagent.jar" wrapper.java.additional.8.stripquotes=TRUE

Note: There may be additional wrapper.java.additional properties defined in other Mule files. These are generated by the system. As indicated by comments preceding these properties, you should not make changes directly to the properties. Mule automatically auto-increments the index number for these properties based on the highest integer number used in wrapper.conf, so you do not need to modify or otherwise account for the index numbers of auto-generated configuration properties.

Oracle WebLogic Startup Settings

On this page: Instrument Oracle WebLogic for Windows Instrument Oracle WebLogic for an Application Running as a Windows Service Instrument Oracle WebLogic for Linux

Rate this page:

The Java Agent bootstraps using the javaagent command line option. Add this option to your

Instrument Oracle WebLogic for Windows

1. Open the startWebLogic.cmd file, located at \user_projects\domains\\bin. 2. Add following javaagent argument to the script.

set JAVA_OPTIONS=% JAVA_OPTIONS% -javaagent:":\\javaagent.jar"

Make sure that the javaagent argument references the full path of the agent installation directory, including the drive, and that the command precedes the WebLogic start commands, for example:

3. Restart the application server. The application server must be restarted for the changes to take effect.

Instrument Oracle WebLogic for an Application Running as a Windows Service Some applications have a pre-compiled startup method that installs WebLogic as a Windows service. Follow these steps to add the agent to the service. 1. Open the script file that starts the application service, such as install_XXXX_Server_Start_Win_Service.cmd. 2. Add the javaagent command before the line starting with "set CMDLINE=%JAVA_VM%..." such as

set CLASSPATH=%MYSERVER_CLASSPATH%;%PRE_CLASSPATH%;%WEBLOGIC_CLASSPATH%;%POST_ CLASSPATH%;%WLP_POST_CLASSpATH%

set JAVA_VM=%JAVA_VM% %JAVA_DEBUG% %JAVA_PROFILE%

set WLS_DISPLAY_MODE=Production

@REM AppDynamics Agent Start set JAVA_OPTIONS=% JAVA_OPTIONS% -javaagent:":\\javaagent.jar" @REM AppDynamics agent END

set CMDLINE=%JAVA_VM% %MEM_ARGS% -classpath %CLASSPATH% %JAVA_OPTIONS% weblogic.Server"

3. Remove the existing Windows Service for your application. From the command line, run this script.

install_XXXXX_Server_Start_Win_Service.cmd XXXXX_xxxxx_Production_Server R

4. Install the Windows Service for your application to include the AppDynamics agent JAVA_OPTIONS argument.

install_XXXXX_Server_Start_Win_Service.cmd XXXXX_xxxx_Production_Server I

5. From the WebLogic web console, stop your application. 6. Start your application (which also starts WebLogic) from the Windows Services application, where the Windows service name = XXXXX_xxxx_Production_Server. 7. Ensure that your application is working properly. For more information, see Creating a Server-Specific Script in the Oracle documentation.

Instrument Oracle WebLogic for Linux

1. Open the startWebLogic.sh file, located at _install_dir>/user_projects/domains//bin. 2. Add the following lines of code to the application server start script.

export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/agent_home/javaagent.jar"

Make sure that the javaagent argument references the full path of the agent installation

directory, including the drive, and that the command precedes the WebLogic start commands, for example:

3. Restart the application server to have the changes take effect.

OSGi Infrastructure Configuration

On this page: Configure Eclipse Equinox Configure Apache Sling Configure Apache Felix for GlassFish Configure JIRA or Confluence Configure Other OSGi-based Containers

Rate this page:

The GlassFish application server versions 3.x and later uses OSGi architecture. By default, OSGi containers follow a specific model for bootstrap class delegation. Classes that are not specified in the container's CLASSPATH are not delegated to the bootstrap classloader; therefore you must configure the OSGi containers for the Java Agentclasses. For more information see GlassFish OSGi Configuration per Domain. To ensure that the OSGi container identifies the Java Agent, specify the following package prefix: