Troubleshooting Java custom instrumentation

Here are some troubleshooting tips for custom instrumentation with New Relic's Java agent.

UI options

You can use New Relic's UI to define instrumentation rules with the Custom Instrumentation Editor, or edit your XML file via your Java app's Settings.

Java apps only: To edit your XML file directly from the New Relic UI: From the New Relic menu bar, select APM > (Applications) > (selected app) > Settings > Live Instrumentation. From here you can:

  • Download a sample XML file.
  • Select an edit existing XML file.
  • Search the instrumentation history.

Nested transactions in thread profiler

Custom instrumentation is useful for nested transactions. For example, in the thread profiler, methods marked [circle] Instrumentation not allowed cannot be instrumented because this can result in unacceptable overhead. However, children of those methods usually can be instrumented.

Thread profiler: Nested transactions colors
APM > Applications > (selected app) > Events > Thread profiler: If a method is marked gray (Instrumentation not allowed), try expanding the thread profile tree to find a nested transaction that you can instrument (white).

To identify methods you can instrument, expand the thread profile tree until you find a suitable method:

  1. From the New Relic menu bar, select APM > Applications > (selected app) > Events > Thread profiler.
  2. Expand the thread profile tree until you find a suitable method.
  3. Follow standard procedures to define and deploy custom instrumentation.

Classes and methods

When troubleshooting custom instrumentation for your Java agent, compare the pointcut information in your newrelic.yml config file with confirmation messages in your log file. Verify that the classes and methods match.

Here is an example:

# This is a pointcut example in your newrelic.yml config file:
<pointcut transactionStartPoint="true">
    <className>com.example.class.name</className>
    <method>
        <name>exampleMethod</name>
    </method>
</pointcut>

If this is being instrumented properly, you may see a message similar to this in the log file:

# This is a confirmation example in your log file:
Oct 1, 2015 10:58:52 -0700 [9805 1] com.newrelic FINER: Instrumenting com/example/class/name

If the log file class and method do not match your custom instrumentation values, review and adjust as needed. (You may not always see a confirmation in your log file about whether the custom instrumentation load succeeded or failed.)

Separate transaction in XML

Here is an example of a pointcut with several method values. The nameTransaction has been added to the XML to break out the method as a separate transaction rather than as a segment in the New Relic APM Transactions breakdown table.

# This is a pointcut example to identify a specific transaction with XML custom instrumentation:
<pointcut>
  <nameTransaction/>
  <className>com.examplename.client.actionflow.impl.exampleActionFlow</className>
  <method>
    <name>requestNAME</name>
    <parameters>
      <type>boolean</type>
    </parameters>
  </method>
</pointcut>

Async transactions

If your app makes use of async processes with custom instrumentation, it may not be possible to connect the async worker activity to the parent transaction. Async processes handle the web transaction in parallel. Many workers handle bits of the request and then reassemble the work to create the complete request.

Most agents do not tie these child transactions together as a single response. This is why you may not be able to identify the transaction in New Relic APM's user interface.

For more help

Additional documentation resources include:

Join the discussion about Java monitoring in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.