Relic Solution: How to disable any or all instrumentation or services in the Java agent

The New Relic Support team often receives requests from users who would like assistance with troubleshooting unexpected resource utilization in their applications. One of the easiest steps to take to check the impact instrumentation is having on an application is to disable specific (or all) instrumentation modules to see if and when performance improves.

In order to view instrumentation modules that the agent has applied out-of-the-box, use the Metrics Explorer to view the application’s Supportability Metrics:

From APM: More Views -> Metrics Explorer -> Search -> type in Supportability/WeaveInstrumentation/Loaded. This should return a list of currently applied instrumentation modules similar to the following:

com.newrelic.instrumentation.tomcat-8.5.2
com.newrelic.instrumentation.jdbc-driver
com.newrelic.agent.instrumentation.pointcuts.container.JasperCompilerPointCut
com.newrelic.instrumentation.tomcat-request-listener
com.newrelic.instrumentation.jdbc-socket
com.newrelic.instrumentation.java.completable-future-jdk8u40
com.newrelic.agent.instrumentation.pointcuts.container.tomcat.FinishResponsePointCut
com.newrelic.instrumentation.jdbc-generic
com.newrelic.instrumentation.jsp-2.4
com.newrelic.agent.instrumentation.pointcuts.container.tomcat.TomcatStartUpPointCut
com.newrelic.instrumentation.servlet-2.4
com.newrelic.agent.instrumentation.pointcuts.container.tomcat.PrepareResponsePointCut
com.newrelic.agent.instrumentation.pointcuts.ProcessPointCut
com.newrelic.instrumentation.jdbc-postgresql-9.4.1208

The fully qualified name of these instrumentation module are defined as the Implementation-Title within the manifest section of the build.gradle for each module - for example, akka-http-core-10.0:

    manifest { attributes 'Implementation-Title': 
'com.newrelic.instrumentation.akka-http-core-10.0' }

How to turn off instrumentation for a specific framework

Add the following to the newrelic.yml file, replacing the [framework_name] line with the relevant entries from the list above:

common: &default_settings
  class_transformer:
    com.newrelic.instrumentation.[framework_name]:
      enabled: false

Note that common: &default_settings should already be present near the top of all newrelic.yml files, and that class_transformer: may be present as well depending on their configuration and agent version. These lines must appear in order (although not necessarily right next to each other), and should not appear twice. YAML syntax is space sensitive, there should be exactly two spaces in front of the first line, four in front of the second line, and six in front of the third line.

Alternatively, you can pass in the following system property to achieve the same result:

-Dnewrelic.config.class_transformer.com.newrelic.instrumentation.[framework_name].enabled=false

To confirm that the desired instrumentation module is disabled, entries similar to the following can be found in the New Relic Agent log:

Dec 1, 2050 11:22:49 -0700 [81094 16] com.newrelic INFO: Instrumentation com.newrelic.[framework_name] is disabled. Skipping.

How to turn off weave instrumentation for a specific class

The excludes functionality works for inner classes as well as their outer classes. As an example, if you wanted to exclude the following inner class AsyncResponder within the outer class ServerRuntime, you would specify it within the excludes stanza like so:

common: &default_settings 
  class_transformer: 
    excludes: 
      org/glassfish/jersey/server/ServerRuntime\$AsyncResponder

There is an escape character preceding $AsyncResponder. The reason for this is because the $ is treated as a special character by regex, and our Agent uses regex to match which classes it should exclude.

In some cases, there may not be a clear instrumentation module to disable, or perhaps there’s only a single class that you might not want to instrument but disabling the module obfuscates too much data. It is possible to specify certain classes by name which should be ignored by the class transformer:

common: &default_settings 
  class_transformer: 
    excludes: 
      org/springframework/jdbc/datasource/LazyConnectionDataSourceProxy, 
      org/springframework/jdbc/datasource/ConnectionProxy

How to turn off instrumentation completely:

When turning off instrumentation completely, you have two options: Disabling the Class Transformer or enabling Lite Mode. To disable the class transformer:

common: &default_settings
  class_transformer: 
    enabled: false

Or you can also pass in the following:

-Dnewrelic.config.class_transformer.enabled=false

Using the above disables transformation of all classes and classloaders in the application. (sans custom instrumentation / FIT extensions). You can confirm that class transformation is disabled by looking for entries similar to the following in the New Relic Agent log:

Jan 1, 2050 14:38:31 -0700 [83969 1] com.newrelic.agent.instrumentation.ClassTransformerServiceImpl INFO: The class transformer is disabled. No classes will be instrumented.

If you choose to use lite_mode:

common: &default_settings
  lite_mode: true

Or you can also pass in the following:

-Dnewrelic.config.lite_mode=true

Lite Mode is a way of running the Java Agent with a Java application that has basic reporting requirements and only needs simple monitoring such as: JMX Metrics, JVM and GC statistics, thread metrics, custom insights events, etc.

In Lite Mode, all of the built in instrumentation is disabled, which means you won’t see Transactions unless you specifically use custom instrumentation to create them. Running the agent in this mode implies an understanding of the trade-off between reporting detail and performance overhead.

To confirm that lite_mode is enabled, entries similar to the following can be found in the New Relic Agent log:

Jan 1, 2050 11:00:44 -0700 [80577 1] com.newrelic INFO: New Relic agent is running in lite mode. All instrumentation modules are disabled

Additional services that can be disabled for troubleshooting:

Disable Transaction Tracing:

  transaction_tracer:
    enabled: false

Disable JMX Metric collection:

  jmx:
    enabled: false

Disable the Circuit Breaker:

  circuitbreaker:
    enabled: false

Disable the Remote Instrumentation Service which provides the ability to add instrumentation via XML (Custom Instrumentation Editor or Extensions):

  reinstrument:
    enabled: false

Disable the collection of Attributes:

  attributes:
    enabled: false

Disable Class Transformation (the basis of all New Relic instrumentation by bytecode manipulation):

  class_transformer:
    enabled: false

Disable the gathering and sending of jars with their version information to the collector:

  jar_collector:
    enabled: false

Disable the Error Collector:

  error_collector:
    enabled: false

Disable the Thread Profiler:

  thread_profiler:
    enabled: false

Disable Distributed Tracing:

  distributed_tracing:
    enabled: false

Disable the collection of Transaction Events:

  transaction_events:
    enabled: false

Disable the Deadlock Detector service:

  deadlock_detector:
    enabled: false
2 Likes