Integrating the New Relic Java APM Agent into Spring Boot: A Step‑by‑Step Task Guide

Desired Outcome

Attach the New Relic Java APM agent to a Spring Boot application, enabling automatic instrumentation of controllers, JPA/Hibernate, and JDBC. Verify that CPU, memory, request, and transaction trace data appear in New Relic One, and be prepared to recover if the agent fails to start or reports missing metrics.

Prerequisites

• Java 8 or newer running the Spring Boot application.
• Valid New Relic license key (available in the New Relic One account).
• Network access from the host to https://jit.newrelic.com for agent download and telemetry ingestion.
• Administrative privileges on the deployment machine to modify JVM startup options or package manifests.

Focused Procedure

1. Download the Agent

   Obtain the latest Java agent JAR from New Relic’s download page or use the provided Maven/Gradle coordinates. For a quick test, place the JAR in the libs/ folder of your project.

2. Configure the Agent

   Two common approaches exist:

   1. Environment Variables (recommended for CI/CD)
      

      export NEW_RELIC_APP_NAME="MySpringApp"
      export NEW_RELIC_LICENSE_KEY="YOUR_LICENSE_KEY"
      export NEW_RELIC_LOG_LEVEL="info"  # optional, defaults to "info"
      

   2. newrelic.yml File
      Create newrelic.yml in the application root or src/main/resources and populate it:
      

      common:
        app_name: MySpringApp
        license_key: YOUR_LICENSE_KEY
        log_level: info
        distributed_tracing:
          enabled: true
        transaction_tracer:
          transaction_threshold: 500ms
          excluded_urls: ["/health", "/metrics"]
      

   Both methods can coexist; environment variables override newrelic.yml values.

3. Attach the Agent to the JVM

   Add the -javaagent flag to the JVM startup command. Example for a standalone Spring Boot JAR:

   java -javaagent:/path/to/newrelic-agent.jar -jar app.jar
   

   For Maven spring-boot:run, set the flag in pom.xml:

   <plugin>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-maven-plugin</artifactId>
     <configuration>
       <jvmArguments>-javaagent:/path/to/newrelic-agent.jar</jvmArguments>
     </configuration>
   </plugin>
   

   For Gradle, add to build.gradle:

   bootRun {
     jvmArgs = ['-javaagent:/path/to/newrelic-agent.jar']
   }
   

4. Enable Distributed Tracing (Optional)

   If the application participates in a microservice mesh, set newrelic.agent.distributed_tracing.enabled=true in newrelic.yml or export the env var NEW_RELIC_TRACING_ENABLED=true. Ensure that downstream services also have the agent and propagate the traceparent header.

5. Deploy and Validate Startup

   After starting the application, watch the JVM console for a line similar to:

   New Relic Java Agent vX.Y.Z started
   

   If this line is absent, the agent failed to initialize. Check the following:

   • Agent JAR path is correct and readable.
   • Java version matches the agent’s supported range (Java 8+).
   • License key is valid (no leading/trailing spaces).
   • No conflicting instrumentation libraries on the classpath.

6. Verify Metrics in New Relic One

   Log into New Relic One, navigate to the APM section, and select the application name you configured. You should see:

   • CPU, memory, and request throughput charts.
   • Transaction traces for Spring MVC endpoints.
   • Database query spans for JPA/Hibernate operations.

   To confirm end‑to‑end tracing, execute an HTTP request to a controller and open the Transaction Traces view. The trace should include the controller method, any repository calls, and the JDBC span.

7. Tune Performance (Optional)

   If the agent adds noticeable overhead, adjust:

   • newrelic.agent.max_transaction_segments – limits the number of segments per transaction.
   • newrelic.agent.transaction_tracer.transaction_threshold – lowers the threshold to capture more transactions.
   • Set log_level: warn to reduce log verbosity.

8. Update or Remove the Agent

   To upgrade, replace the JAR with a newer version and restart the application. For a clean rollback, comment out or delete the -javaagent flag and ensure the JAR is no longer on the classpath. No data is lost; the application simply stops sending telemetry.

Expected Checks

• JVM startup log contains the agent start line.
• New Relic One displays the application under the APM list.
• CPU and memory metrics appear within a few seconds of startup.
• Transaction trace for a test endpoint includes at least two spans: controller and database.
• Distributed tracing headers propagate across two services (verify by inspecting the trace view).

Recovery Options

• Agent Startup Failure
  • Verify the JAR path and permissions.
  • Run newrelic-admin detect against the JAR to confirm Java version compatibility.
  • Ensure the license key is correct and not expired.
• Missing Metrics
  • Check that newrelic.yml or env vars are loaded (use newrelic-admin dump to view current settings).
  • Confirm that the application’s port is not blocked by a firewall that prevents telemetry to jit.newrelic.com.
  • Verify that no other instrumentation library (e.g., Micrometer) is overriding New Relic’s instrumentation.
• Excessive Overhead
  • Reduce transaction_tracer.transaction_threshold or max_transaction_segments.
  • Exclude high‑volume URLs with excluded_urls to focus on critical paths.
  • Increase JVM heap if the agent’s memory usage is approaching limits.
• License Quota Exceeded
  • Monitor the Limits page in New Relic One for ingestion thresholds.
  • Apply transaction_tracer.excluded_sql_statements to drop noisy queries.
  • Consider upgrading the New Relic plan if sustained high ingestion is required.

Conclusion

By following this task guide, you can reliably attach the New Relic Java agent to a Spring Boot application, verify that instrumentation is active, and address common pitfalls. The agent’s automatic instrumentation reduces manual code changes, while its configurability allows fine‑tuning for performance and data‑volume constraints.