Install the Java agent in GAE flexible environment

This page covers installing the New Relic Java agent in a Google App Engine (GAE) flexible environment using a custom Docker runtime.

Do not use the GAE standard environment or Google App Engine's "native mode" — the Java agent requires a custom runtime.

Compatibility and requirements

Java 8, 11, 17, 21, 24, 25, and 26 (Java 7 supported on agent v6.5.4 and earlier only)
Google App Engine flexible environment with a custom Docker runtime
See compatibility and requirements for supported framework and library version ranges

GAE standard environment — requires a custom runtime; standard environment does not support it
GAE native mode — the Java agent requires a custom runtime
Running alongside other APM agents — the Java agent cannot guarantee correct behavior when another APM agent is active in the same JVM

A New Relic account and
A JVM with SHA-2 (256-bit) SSL support
A Google Cloud Platform project with an App Engine application created (see Google App Engine procedures for Java)
The gcloud CLI installed and initialized (see Google Cloud SDK docs)
Maven or Gradle with the App Engine plugin configured

Download newrelic-java.zip and unzip it into your project: [#install-step-1]

bash

$curl -O https://download.newrelic.com/newrelic/java-agent/newrelic-agent/current/newrelic-java.zip
$unzip newrelic-java.zip

Configure your app.yaml for a custom runtime:

runtime: custom
env: flex

Configure your Dockerfile to add the agent and pass the -javaagent argument. The example below uses Tomcat:

ADD ./newrelic/newrelic.jar /usr/local/tomcat/newrelic/newrelic.jar
ENV JAVA_OPTS="$JAVA_OPTS -javaagent:/usr/local/tomcat/newrelic/newrelic.jar"

Build your project:

bash

$mvn clean install

Edit newrelic/newrelic.yml and set the two required values:

For all other configuration options, see Java agent configuration.

Deploy to GAE:

bash

$gcloud --project YOUR_PROJECT_NAME app deploy

Wait until the deployment completes. Send at least two requests, then wait 2–3 minutes and your app appears in APM & services.

If no data appears after five minutes, see No data appears (Java).