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:
- Set up your application and install necessary GAE-related dependencies for custom runtimes. Include the New Relic Java agent in the project.
- Configure Maven or Gradle as applicable.
- Configure the
app.yaml
file. - Configure the Dockerfile.
- Build the Docker image.
- Deploy the Docker image to the initialized GAE flexible environment.
- Recommendation: Disable GAE health checks.
For more information about deploying and configuring your Java app in the GAE flexible environment, see:
- Google App Engine's documentation for Java
- Google App Engine's tutorials to deploy a Java app
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
-
- Follow standard procedures to install the Java agent as necessary for your specific app server, and obtain your license key.
- 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.
- 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.- 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. -
After adding the Java agent dependencies to the
pom.xml
, build your application by running:mvn clean install
- Check your project's
target
directory to find the app'sWAR
file and an unzippednewrelic
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. - Add the Java agent dependencies to the project's
- 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
andcatalina.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 yourdocker 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
-
-
To deploy your Docker image to your initialized GAE flexible environment, run the following command:
gcloud app deploy
- Wait until the deployment completes.
-
To open the app in the browser, run the following command:
gcloud app browse
- 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:
- To connect to the GAE instance and start a shell in the Docker container running your code, see Debugging an Instance.
-
To redirect New Relic Java agent logs to Stackdriver in the Cloud Platform Console, change the
newrelic.yml
file to:log_file_name: STDOUT
- To view the logs, use the Cloud Platform Console's Log Viewer.