Getting started with Java

Compatibility

The probe is compatible with the java version 8 or higher and up to java 17.

Steps

  1. Download probe from Nudge.

  2. Create a directory and extract ZIP file contents to it.
    • nudge-x.y.z.jar and nudge.properties files must stay in the same directory.
    • java agent file have naming constraints : either keep original name nudge-x.y.z.jar or rename to nudge.jar.

  3. [ Optional ] Customize configuration as described below.

  4. Add the -javaagent argument to the JVM startup command line & configure OSGI if required. The procedure depends on the container.

       - ![Tomcat](/images/logo-installation/tomcat.svg) [Tomcat](#tomcat)
   - ![JBoss](/images/logo-installation/jboss.png) [JBoss & Wildfly](#jboss-wildfly)
   - ![Glassfish](/images/logo-installation/glassfish.png) [Glassfish](#glassfish)
   - ![Weblogic](/images/logo-installation/weblogic.jpg) [Weblogic](#weblogic)
   - ![Websphere](/images/logo-installation/websphere.png) [Websphere](#websphere)
   - ![JOnAS](/images/logo-installation/JOnAS.png) [JOnAS 5.1](#jonas-5-1)
   - ![JOnAS](/images/logo-installation/JOnAS.png) [JOnAS 5.2](#jonas-5-2)
   - ![Liferay](/images/logo-installation/liferay.png) [Liferay](#liferay)
  5. Restart your container/JVM.

Options

The Java probe configuration is provided through:

nudge.properties file can be made optional by providing parameters as JVM system properties.

See parameters reference for further details.

Deployment and application identifier

Nudge APM gather metrics about your application and its environment by using a Nudge agent. This agent depends on the way your application is built.

Metrics are sent by using the encrypted HTTPS protocol (by default) towards the Nudge controler that will store and analyze them.

Agent binding

The app_id parameter is the only mandatory parameter and the most important. Its value defines the link between your JVM and the Nudge application. An appropriate value is automatically supplied in the nudge.properties file available in the downloaded file. Then there is nothing to do if you consider your application on a single JVM.

Several JVMs for a single application

You might have a cluster of server that correspond to the same business application. In this case, you should configure the app_id parameter of all JVMs so that they the same value. The metrics will then be aggregated in the same nudge application. However, Nudge APM is still able to differenciate the servers/JVMs for local metrics (bound with a particular server).

Agent on cluster

Several applications on the same JVM

A Nudge agent is tied with the JVM. But this is possible to deploy many archives (typically WAR, EAR files) on the single JVM of the container or application server. In this case, there is only one agent and then only one app_id value. Then all metrics of deployed archives will be aggregated as a single Nudge application.

Agent on AS

In order to distinguish transactions of an archive from others are available and discuted there.

JMX

The configuration of the JMX attributes observation on Nudge-APM is made by properties of the probe via the attributes activate_jmx and mbeans_monitored.

activate_jmx=true
mbeans_monitored=<mbean1>;<mbean2>;...

To obtain the exact syntax of every MBean, we recommend to use the tool JConsole supplied with the JDK:

jmx_mbean_probe-1

Note that certain application servers * (for example Tomcat 5.5) * don’t systematically publish in the JMX arborescence of the JVM.

If you can’t obtain the information via JConsole, we invite you to refer to the documentation of your application server.

For example, to follow the number of active sessions on the application servlets-examples of a named server Tomcat:

activate_jmx=true
mbeans_monitored=Catalina:type=Manager,path=/servlets-examples,host=localhost

*After restart of the JVM, you can then list all the attributes *(activeSessions) through UI: **

jmx_mbean_probe-2

Standalone application / JVM

Use this if you use an executable jar or a Spring Boot application.

You only need to add the -javaagent JVM argument with the full path to probe .jar file.

java -javaagent:c:/full/path/to/nudge-x.y.z.jar -jar myapp.jar

Containers and application servers

Tomcat

Add -javaagent parameter to JVM parameters

If Tomcat is installed as a service, the file bin\setenv.bat is ignored.
In this case, you have to use the tool tomcat7w.exe (please replace the ‘7’ with the appropriate version of your Tomcat if needed).

bin/tomcat7w.exe //ES//tomcat7service

Then, from the Java tab, you should add the following line in the field Java Options :

-javaagent:c:/full/path/to/nudge-x.y.z.jar

You could find more information about the configuration of Tomcat as a service under Windows in official documentation.

JBoss and Wildfly

Configuration differs slightly for Jboss/Wildfly versions. Please check your version before changing configuration.

Listing versions of RedHat JBoss EAP builded over open-source versions.

JBoss 4, JBoss 5 (EAP and community versions)

Add the following lines at the end of the file :

Under Unix/Linux, edit bin/run.conf

JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/nudge-x.y.z.jar -Djboss.platform.mbeanserver"

Under Windows, edit bin\run.conf.bat

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:c:/full/path/to/nudge-x.y.z.jar -Djboss.platform.mbeanserver"

JBoss AS 7 - JBoss EAP 6, 7 - Wildfly 8, 9, 10

When jboss.modules.system.pkgs parameter is already set, you should add ,org.nudge to existing value (values are comma-separated).

Standalone

Under Unix/Linux, edit bin/standalone.conf

JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.nudge"
JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/nudge-x.y.z.jar"

Under Windows, edit bin\standalone.conf.bat

set "JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.nudge"
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:c:/full/path/to/nudge-x.y.z.jar"
Domain

Use CLI tool bin/jboss-cli.sh on Unix/Linux or bin\jboss-cli.bat on Windows, use connect command to connect to cluster.

List existing servers with command below (assuming master node is master).

/host=master:read-children-names(child-type=server)

Sample output with 3 nodes :

{
    "outcome" => "success",
    "result" => [
        "server-one",
        "server-three",
        "server-two"
    ]
}

Then for each server (here for server-one), execute both commands. We recommand using a distinct copy of nudge.jar for each node.

/host=master/server-config=server-one/system-property=jboss.modules.system.pkgs:add(value="org.jboss.byteman,org.nudge")

/host=master/server-config=server-one/jvm=default:add(java-agent=/path/to/nudge.jar)

Then restart server.

Glassfish

Configuration is made in two steps :

WebLogic

Under Unix/Linux, edit startWebLogic.sh file from the directory bin of the domain and add the following line:

export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/full/path/to/nudge-x.y.z.jar

Under Windows, edit the file startWebLogic.bat from the directory bin of the domain and add the following line:

set "JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:c:/full/path/to/nudge-x.y.z.jar"

Java5 or probes < 3.0.10 only

Weblogic default configuration does not allow to connect to sites using wildcard certificates like *.nudge-apm.com. Thus, you have to update server configuration :

Websphere

Steps for Websphere 9, on other versions navigation and items naming may vary slightly but procedure remains identical.

JOnAS 5.1

Extract from the JAR archive $JONAS_ROOT/lib/bootstrap/felix-launcher.jar the file org/ow2/jonas/launcher/felix/default-config.properties.

Then copy and rename the file as $JONAS_BASE/conf/felix-config.properties.

Edit this new file felix-config.properties and add the following properties:

org.osgi.framework.bootdelegation= (...) \
	org.nudge, \
	org.nudge.*

org.osgi.framework.bundle.parent=app

Add the following values to the property excluded_classpath of the file nudge.properties:

excluded_classpath=org.ow2.carol.jndi,org.ow2.util,org.ow2.jonas.ee.jdbc,$Proxy

Add the following lines into the file setenv.sh:

JAVA_OPTS=$JAVA_OPTS -Djonas.felix.configuration.file=$JONAS_BASE/conf/felix-config.properties
JAVA_OPTS=$JAVA_OPTS -javaagent:/path/to/nudge-x.y.z.jar

JOnAS 5.2

Add the following properties into the file gateway.properties:

org.osgi.framework.bootdelegation=${bootdelegation-packages},org.nudge.*
org.osgi.framework.bundle.parent=app

Add following values to property excluded_classpath in nudge.properties (add property if it does not exists)

excluded_classpath=org.ow2.carol.jndi,org.ow2.util,org.ow2.jonas.ee.jdbc,$Proxy

Add the following line into the file setenv.sh in order to add the parameter -javaagent:

JAVA_OPTS=$JAVA_OPTS -javaagent:/path/to/nudge-x.y.z.jar

Liferay

Configure Wildfly/Tomcat bundle

See Tomcat and Wildfly sections for details.

Configure OSGI (Liferay 7.x)

Extract portal.properties from portal-impl.jar and open file with a text editor.

Copy module.framework.properties.org.osgi.framework.bootdelegation property to portal-ext.properties

Add org.nudge.* to module.framework.properties.org.osgi.framework.bootdelegation value

module.framework.properties.org.osgi.framework.bootdelegation=\
	<... other lines ommited for clarity ..>
	sun.*,\
	org.nudge.*

Probe upgrade

New versions of the java probe bring new features (and sometimes bugfixes). That’s why it is important to consider its upgrade.

Procedure

Upgrade procedure depends on the way the agent has been installed. If the installation process of our documentation has been followed, the upgrade procedure should be similar to this :

  1. Download the latest probe available (See more information here about the download step).

  2. [ Optional ] Rename the downloaded probe file according to its constraints. You might consider to use symbolic link.

  3. [ Optional ] Move the new probe file into the directory of the current probe (if it is not already in that directory). If your use a symbolic link, you should rather update the link (with the command ln -s for example).

  4. [ Optional ] You might want to customize the probe configuration. New options would then be activated after the restart of the JVM with the new probe. A new probe version might accept new options.

  5. [ Optional ] backup the current probe file.

  6. [ Optional ] Potentially change the JVM javaagent argument. This is not needed if your use the nudge.jar naming convention or a symbolic link. Otherwise please follow the installation instruction depending on your container in order to update the javaagent argument.

  7. Restart the JVM (or application container); the new probe is taken into account!

Warnings

You get informed about how old is your probe directly from the application list screen. A little exclamation mark appears as soon as we detect that the probe could be upgraded. If the probe gets quite old, this exclamation mark is highlighted with a red color.

probe-warn

Backward compatibility

Even if the installed probe is not the latest version, information will still be correctly processed and rendered by the portal. Probe version are backward compatible regarding the communication protocol used between the probe and the portal.

Download links

The latest stable probe can be downloaded from this link. You should be connected to the support portal.

File naming constraint

The classpath that you provide can ignore the probe (and it will add itself into the classpath automatically). But, in order to work, a java probe JAR file must have a particular name. The file name of the probe can be either :

We are not able to work around this constraint about the file name (without another classpath argument provided to the JVM). Indeed, the java probe must be included into the classpath, and the file’s name must be known for that purpose. The inclusion of the probe into the classpath is made through the MANIFEST of the probe itself, so that you don’t have to bother about it. For more information about that subject, you can check the description of the Boot-Class-Path attribute from the documentation of the java.lang.instrument package.

You may use symbolic links (for UNIX-like systems) in order to configure the path of the agent for the JVM. In this case, the target of the symbolic link must conform to the convention regarding the file name.

You can also use the readlink command as an helper. As an example with Tomcat and a symbolic link located at /usr/local/nudge/nudge.jar, your configuration might looks like that:

export CATALINA_OPTS="$CATALINA_OPTS -javaagent:$(readlink -f /usr/local/nudge/nudge.jar)"