Install New Relic Java agent in GAE flexible environment

With APM's Java agent, you can monitor applications that reside in the Google App Engine (GAE) flexible environment. Adding New Relic to your GAE flex app gives you insight into the health and performance of your app and extends GAE with metrics you can view in APM, Browser, and dashboards.

This document explains how to add New Relic to your GAE flex app by configuring a custom runtime, and gives an example of deploying a Tomcat app with Docker.

The New Relic Java agent can run in a GAE flexible environment using a custom runtime. Due to limitations of other environments, do not use the GAE standard environment or Google App Engine's "native mode" installation.

Build a custom runtime using Docker

See Google's documentation for building custom runtimes. There are many ways to build a custom runtime that contains the New Relic Java agent (for example, using Tomcat). In general, to build a custom runtime:

  1. Set up your application and install necessary GAE-related dependencies for custom runtimes. Include the New Relic Java agent in the project.
  2. Configure Maven or Gradle as applicable.
  3. Configure the app.yaml file.
  4. Configure the Dockerfile.
  5. Build the Docker image.
  6. Deploy the Docker image to the initialized GAE flexible environment.
  7. Recommendation: Disable GAE health checks.

For more information about deploying and configuring your Java app in the GAE flexible environment, see:

GAE flex example with Tomcat

This example describes how to add New Relic to your GAE flex app by installing the New Relic Java agent, building a custom runtime, and deploying an application WAR to Tomcat. Be sure to install the Java agent as necessary for your specific app server.

1. Set up GAE flexible project and install dependencies
  1. Follow standard procedures to install the Java agent as necessary for your specific app server, and obtain your license key.
  2. Follow Google App Engine procedures for Java to create a new Cloud Platform project, create an App Engine application, and complete other prerequisites for the Google Cloud SDK.
  3. Install any necessary dependencies, such as the Maven or Gradle App Engine plugin, and Java.

The Google Cloud SDKprovides the gcloud command line tool to manage and deploy GAE apps.

2. Configure Maven pom.xml to include Java agent and build project

This example uses Maven to build the project, a Docker Tomcat image to run it, and the gcloud command line tool to deploy the Docker image to a GAE flexible environment.

  1. Add the Java agent dependencies to the project's target directory when the project is built, when you download and unzip all Java agent components.

  2. After adding the Java agent dependencies to the pom.xml, build your application by running:

    mvn clean install
  3. Check your project's target directory to find the app's WAR file and an unzipped newrelic directory.

These files will be incorporated into a Docker image.

You can also add the App Engine Maven or Jetty Maven plugin to your pom.xml. This will allow you to use Maven to deploy your app to a GAE flexible environment.

3. Configure your app.yaml

The app.yaml configuration file is required for a GAE flexible environment app with a custom runtime. At a minimum, make sure it contains:

env: flex
runtime: custom
4. Configure the Dockerfile

The Dockerfile defines the Docker image to be built and is required for a GAE flexible environment app. In the following Dockerfile example code, the newrelic.yml and catalina.sh files have been configured locally, to replace those already copied to the Docker image. (You can add your New Relic license key directly to your Dockerfile, or use an environment variable in your docker run command.)

# base Tomcat image to build Docker image from
FROM tomcat:8.5.14-jre8

MAINTAINER Jane Doe <janedoe@mail.com>

# Tomcat directory to copy Java agent files to
ENV NEWRELIC_HOME /usr/local/tomcat/newrelic

# copy application war from target to Tomcat webapps
ADD target/*.war /usr/local/tomcat/webapps

# copy Java agent files from target to Tomcat NEWRELIC_HOME
ADD target/newrelic ${NEWRELIC_HOME}

# update Java agent yml with license_key and app_name and copy to image  
ADD newrelic.yml ${NEWRELIC_HOME}

# update catalina.sh with -javaagent:/path/to/newrelic.jar and copy to image 
ADD catalina.sh /usr/local/tomcat/bin/
5. Build the Docker image

To build a Docker image that runs Tomcat with the New Relic Java agent monitoring your deployed application WAR, run the following command. Be sure to include the period at the end of the code, to indicate the current directory contains the build files.

docker build -f Dockerfile -t newrelic-tomcat .

After running this command, verify that you have a Docker image named newrelic-tomcat.

6. Deploy Docker image to initialized GAE flexible environment

  1. To deploy your Docker image to your initialized GAE flexible environment, run the following command:

    gcloud app deploy
  2. Wait until the deployment completes.

  3. To open the app in the browser, run the following command:

    gcloud app browse
  4. To view your GAE flex app data in New Relic, go to the APM Summary page.

Recommendation: Disable health checks

Google App Engine sends periodic health check requests to confirm that an instance has been successfully deployed, and to check that a running instance maintains a healthy status. A health check is an HTTP request to the URL /_ah/health.

If you create a custom runtime, your app must be able to handle a large number of health check requests. Otherwise, your app data may not display correctly in APM. To avoid adding additional instrumentation overhead and skewing throughput for your application, we recommend that you disable the health check.

Recommendation: Configure your app.yaml to disable health checks by adding:

health_check:
  enable_health_check: False

Get Java agent troubleshooting logs from GAE

Use these resources to troubleshoot your GAE flex environment app:

For more help

If you need more help, check out these support and learning resources: