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.

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:

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

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.

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.

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:

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.