Instrumenting Java App with New Relic Agent

This tutorial demonstrates how to integrate the New Relic monitoring agent in a Java application running on Apcera.

Get the New Relic Agent

Create a New Relic account or log in to your existing New Relic account.

Under the APM tab, select the Java web agent to install.

NOTE: If you already have an account, in the APM tab select Add more, then select the Java agent.

screenshot

Get the license key by selecting "Reveal license key" and copying the key to a text file.

screenshot

Download the Java agent newrelic-java-x.xx.x.zip to your local machine. (This step is optional since we will build the package using a script.)

screenshot

Clone the sample apps repo

Clone the Apcera sample apps from the GitHub repository:

git clone git@github.com:apcera/sample-apps.git

The directory \sample-apps\example-java-war\ is the working directory for this tutorial.

Download the New Relic Java package script (if necessary)

First, check if the New Relic package for Java exists in your cluster.

apc package list --provides newrelic-java --namespace /
Working in "/"
╭──────────────────────┬──────────────────────┬───────╮
│ Name                 │ Namespace            │ State │
├──────────────────────┼──────────────────────┼───────┤
│ newrelic-java-3.20.0 │ /apcera/pkg/packages │ ready │
╰──────────────────────┴──────────────────────┴───────╯

If this package does not exist, Apcera provides a package script for creating the New Relic Java package in the Apcera package scripts repository: https://github.com/apcera/package-scripts.

The New Relic Java package script file is located at https://github.com/apcera/package-scripts/blob/master/packages/newrelic-java-3.28.0.conf.

To download this script file, select the file newrelic-java-3.28.0.conf in the GitHub interface, click Raw, right-click and select Save Page As.

Save the package script file to the \sample-apps\example-java-war\ working directory.

Create the New Relic Java package

We use a package script file to build the New Relic Java package for Apcera.

In this example we specify the New Relic license key on the command line. Alternatively you can add the license key to the package script file (line 34). Note that the package script file supports the newrelic-java-3.28.0 agent. If you are using a different agent version, update the package script file before running it.

Create the New Relic Java agent package by executing the following series of commands.

Target your Apcera cluster and log in using APC.

apc target <cluster-name>.apcera-platform.io

apc login

CD to the app directory:

cd /apcera/sample-apps/example-java-war

Create the package:

apc package build newrelic-java-3.28.0.conf

When the package is successfully built, run the following command to verify:

apc package list -ns /

You should see the newrelic-java-3.28.0 package in the /apcera/pkg/packages namespace.

To verify the package details:

apc package show package::/apcera/pkg/packages::newrelic-java-3.28.0
╭───────────────────┬─────────────────────────────────────────────────────╮
│ Package:          │ newrelic-java-3.28.0                                │
├───────────────────┼─────────────────────────────────────────────────────┤
│ FQN:              │ package::/apcera/pkg/packages::newrelic-java-3.28.0 │
│ State:            │ ready                                               │
│                   │                                                     │
│ Created by:       │ admin@apcera.me                                     │
│ Created at:       │ 2016-04-22 21:27:46.213672254 +0000 UTC             │
│ Updated by:       │ staging_coordinator@apcera.me                       │
│ Updated at:       │ 2016-04-22 21:27:55.515865027 +0000 UTC             │
│                   │                                                     │
│ Staging Pipeline: │ stagpipe::/apcera::compiler                         │
│ Stagers:          │ job::/apcera/stagers::compiler                      │
│ Dependencies:     │ os: linux                                           │
│                   │ package: apache-tomcat                              │
│                   │ runtime: java                                       │
│ Provides:         │ package: newrelic-java-3.28.0                       │
│                   │ package: newrelic-java-3.28                         │
│                   │ package: newrelic-java-3                            │
│                   │ package: newrelic-java                              │
╰───────────────────┴─────────────────────────────────────────────────────╯

Create a Java app with New Relic monitoring

Create a version of the example-java-war app with an embedded New Relic Agent. Use -ae (--allow-egress) to allow egress and -do (--depends-on) to specify the Java New Relic package you created, and include the license key on the command line as shown below.

apc app create my-java-war --allow-egress --env-set 'JAVA_OPTS=$JAVA_OPTS -Dnewrelic.config.license_key=5e4705e22ff5349aa1cb6a657a8bf65da4de2ec2 -Dnewrelic.config.app_name=my-java-war' --depends-on package.newrelic-java-3.28.0

You should see a "Success! message. You can ignore any stderr messages you may see in the output.

Start the app:

apc app start my-java-war

Monitor your Java app using New Relic

Go to your New Relic console. In a few minutes your application will start sending information to New Relic.

screenshot

To see see more data, exercise the app by visiting the URL provided in the output of the apc app start command. Click on the JSP page and servlet links several times to generate metrics for both of the corresponding transactions.

screenshot