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 > APM > (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.
To use the custom instrumentation editor, you must meet the following requirements:
|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 > 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.
- Expand individual methods to locate uninstrumented [circle-o] 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.
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.
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.
The Instrumentation page supports the following features:
|If you want to...||Do this...|
|Pause or disable custom instrumentation||
|Import existing instrumentation|
|Edit or delete instrumentation points||
You cannot edit manual instrumentation, only delete it.
|View instrumentation history||
You can define the following options with the custom instrumentation editor:
|Instrument methods||Begin instrumenting the selected method. Instrumented methods will be visible in the New Relic UI. Instrument supports the following child options:
|Report custom attributes||Method parameters can be captured as attributes on a transaction. New Relic reports these attributes to transaction traces, traced errors, and New Relic One
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
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:
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:
If a transaction is not on that thread and the Start the transaction flag is not checked: