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 use the custom instrumentation editor: Go to one.newrelic.com > All capabilities > APM & services > (select a Java app) > Settings > Instrumentation. Use the custom instrumentation editor to:

Instrument an unsupported framework.
Gain additional insight into uninstrumented methods.
Ignore particular transactions.

Requirements

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

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

Define custom instrumentation

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:

Create a new thread profiler session. To ensure you collect sufficient data, set the length of the session to at least two minutes.
Go to one.newrelic.com > All capabilities > APM & services > (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.
Expand individual methods to locate uninstrumented methods.
To define instrumentation rules for particular nodes, select Instrument or Ignore, and customize the rules if necessary.
To save your settings, select Confirm instrumentation changes.
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.

Caution

Avoid over-instrumenting whenever possible. With each additional method that is instrumented, the agent will be using more resources and your application will incur more overhead. In addition, deploying your instrumentation will cause 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

You can also create instrumentation points directly in the editor 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.
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.

Important

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 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	You cannot edit manual instrumentation, only delete it. Select Remove to stop instrumenting a particular method. Select Edit to change the instrumentation rules.
View instrumentation history	You can view each previous iteration of your custom instrumentation from the Instrumentation history tab, including 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

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 `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.

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 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?
If a pre-existing transaction is on that thread and the Start the transaction flag is checked: The agent ignores the Start the transaction flag. 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: The agent discovers there is no current transaction. 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: The agent looks for a transaction on that thread and does not find one. The metric is dropped.

Is the "Start the transaction" flag checked?

Yes

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

The agent ignores the Start the transaction flag.
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:

The agent discovers there is no current transaction.
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:

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