Custom Instrumentation Editor: Instrument from UI

New Relic's custom instrumentation editor allows Java app users to implement custom instrumentation via the New Relic user interface. The editor is the preferred choice when you cannot modify your application code and don't have that many methods to instrument. See Java custom instrumentation for other instrumentation options and the reasons for using each.

To find the custom instrumentation editor: Go to https://rpm.newrelic.com/apm (select a Java app) > Settings > Instrumentation. Use the custom instrumentation editor to:

Access to this feature depends on your subscription level.

Requirements

To use the custom instrumentation editor, you must meet the following requirements:

Requirement Comments
Agent Java agent version 3.17.0 or higher
Account role Owner or Admin
Security Users of high security mode must export their instrumentation and manually import it to their app server.

Define custom instrumentation

Owner or Admins

To define custom instrumentation from the New Relic user interface, use a thread profiling session to collect detailed stack traces of each thread in your application. If possible, test your custom instrumentation in a pre-production environment before changing the instrumentation rules in your production app. In either environment, use the custom instrumentation editor to define the methods you want instrumented, and apply your changes:

  1. Create a new thread profiler session. To ensure you collect sufficient data, set the length of the session to at least two minutes.
  2. Go to rpm.newrelic.com/apm > (select an app) > Settings > Instrumentation. Scroll down to the bottom of the page until you see the Recently collected thread profiles list, then select the most recent thread profile.
  3. Expand individual methods to locate uninstrumented [circle-o] methods.
  4. To define instrumentation rules for particular nodes, select Instrument or Ignore, and customize the rules if necessary. Ensure you avoid excessive instrumentation.
  5. To save your settings, select Confirm instrumentation changes.
  6. Deploy your changes from the Instrumentation page:

    • To deploy your changes automatically, select Deploy instrumentation changes.
    • To deploy your changes manually, select Export XML, and see exporting your instrumentation.

Deploying your instrumentation causes a brief period of higher overhead. This can noticeably slow application requests for several seconds.

If you applied your changes from the UI, the agent will begin instrumenting your methods within a few harvest cycles (typically a few minutes).

Manual instrumentation using the editor

Instrumentation points can also be created in the editor directly without using a thread profile. From the custom instrumentation editor, select Add manual instrumentation to manually enter a class and method to be instrumented or ignored. Follow the custom instrumentation by XML rules when defining your instrumentation points. Then, deploy your changes from the instrumentation editor.

Using this method to add instrumentation exposes additional functionality beyond what is available from a thread profile. In addition to matching methods by signature, you can also instrument methods by return type, methods on interfaces, and by Java annotation.

These more complex instrumentation types can be created and deleted in the editor, but not edited.

If a method is marked Instrumentation not allowed, follow New Relic's troubleshooting procedures for custom instrumentation.

Deploy changes manually

You can also use the custom instrumentation editor to build a custom instrumentation set, then export an instrumentation file and manually import it to your app server. This is required for users of high security mode.

To export your instrumentation, define custom instrumentation via the UI. Then select Export xml from the Instrumentation page, and import the file on your app server.

Page functions

The Instrumentation page supports the following features:

If you want to... Do this...
Pause or disable custom instrumentation Select [ban-circle] Disable instrumentation to temporarily disable all UI-defined custom instrumentation. Select Enable instrumentation to re-enable your instrumentation settings.
Import existing instrumentation You can import an existing custom instrumentation xml file by selecting Import xml. You can also Export xml if you do not want to deploy your changes automatically.
Edit or delete instrumentation points Select Remove to stop instrumenting a particular method. Or, select Edit to change the instrumentation rules. You cannot edit manual instrumentation, only delete it.
View instrumentation history You can view each previous iteration of your custom instrumentation from the Instrumentation history tab. See who deployed changes and when. You can restore an old version by selecting export to download a copy of the custom instrumentation file, then importing it to the instrumentation editor.

Instrumentation options

Owner or Admins

You can define the following options with the custom instrumentation editor:

Instrumentation options Comments
Instrument methods Begin instrumenting the selected method. Instrumented methods will be visible in the New Relic UI. Instrument supports the following child options:
  • Name the transaction (transaction name): Override the standard transaction name, defined by the automatic naming rules. The UI will instead use the listed name.
  • Start the transaction when this method executes: Rather than including metrics from this metric inside its parent transaction, create a new transaction for this method. Agent behavior with this option depends on whether there is a pre-existing transaction on the thread.
Report custom attributes Method parameters can be captured as attributes on a transaction. New Relic reports these attributes to transaction traces, traced errors, and Insights Transaction events.

For security reasons, capturing custom attributes using the Custom Instrumentation Editor is disabled by default and cannot be enabled while you are using High security mode. If you want to report custom attributes using the Custom Instrumentation Editor and you do not want the Java agent to be in High security mode, disable High security mode and then add the following text in the common: block of your newrelic.yml:

reinstrument:
    attributes_enabled: true
Ignore transactions Ignore this method entirely. The agent will not report metrics from this method, and the method will not contribute to Apdex calculations.

Results with "start" option

If you select Instrument methods > Start the transaction when this method executes, agent behavior depends on whether there is a pre-existing transaction on the thread.

When the class or method is instrumented:

Is the "Start the transaction" flag checked?
Yes No

If a pre-existing transaction is on that thread and the Start the transaction flag is checked:

  1. The agent ignores the Start the transaction flag.
  2. The agent includes the class/method into the pre-existing transaction.

If a pre-existing transaction is on that thread and the Start the transaction flag is not checked, the agent includes the class/method into the pre-existing transaction.

If a transaction is not on that thread and the Start the transaction flag is checked:

  1. The agent discovers there is no current transaction.
  2. The agent creates a new transaction starting with the class/method you have instrumented.

If a transaction is not on that thread and the Start the transaction flag is not checked:

  1. The agent looks for a transaction on that thread and does not find one.
  2. The metric is dropped.

For more help

Recommendations for learning more: