--- title: Custom instrumentation editor: Instrument from UI source: https://docs.newrelic.com/docs/apm/agents/java-agent/custom-instrumentation/custom-instrumentation-editor-instrument-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](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/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](https://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](https://docs.newrelic.com/docs/agents/java-agent/instrumentation/blocking-instrumentation-java). ## 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](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security) must [export their instrumentation](#manual-deploy) and manually import it to their app server. | ## Define custom instrumentation [#defining] 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](https://docs.newrelic.com/docs/apm/applications-menu/events/thread-profiler-dashboard#starting). To ensure you collect sufficient data, set the length of the session to at least two minutes. 2. Go to **[one.newrelic.com > All capabilities](https://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. 3. Expand individual methods to locate uninstrumented methods. 4. To define instrumentation rules for particular nodes, select **Instrument** or **Ignore**, and [customize the rules if necessary](#options). 5. To save your settings, select **Confirm instrumentation changes**. 6. Deploy your changes from the [**Instrumentation** page](#dashboard): - To deploy your changes automatically, select **Deploy instrumentation changes**. - To deploy your changes manually, select **Export XML**, and see [exporting your instrumentation](#manual-deploy). > #### ⚠️ 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](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/glossary#harvest-cycle) (typically a few minutes). ## Manual instrumentation using the editor [#manual-instrumentation] You can also create instrumentation points directly in the editor without using a thread profile: 1. From the custom instrumentation editor, select **Add manual instrumentation** to manually enter a class and method to be instrumented or ignored. 2. Follow the [custom instrumentation by XML rules when defining your instrumentation points](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-custom-instrumentation-xml-examples#file-format). 3. 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](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/troubleshooting-java-custom-instrumentation). ## Deploy changes manually [#manual-deploy] 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](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security). To export your instrumentation, [define custom instrumentation via the UI](#defining). Then select **Export xml** from the **Instrumentation** page, and [import the file on your app server](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-xml#file-location). ## Page functions [#dashboard] 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](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-xml) by selecting **Import xml**. - You can also **Export xml** if you [do not want to deploy your changes automatically](#manual-deploy). | | Edit or delete instrumentation points | You cannot edit [manual instrumentation](#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](#import) it to the instrumentation editor. | ## Instrumentation options [#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](https://docs.newrelic.com/docs/agents/java-agent/instrumentation/naming-web-transactions). 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](#start-results) 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](https://docs.newrelic.com/docs/agents/java-agent/getting-started/apm-agent-security-java). 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](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#cfg-enable_high_security) and then add the following text in the `common:` block of your **newrelic.yml**: ````yml reinstrument: attributes_enabled: true ``` ```` | | Ignore transactions | [Ignore this method entirely](https://docs.newrelic.com/docs/agents/java-agent/instrumentation/blocking-instrumentation-java). The agent will not report metrics from this method, and the method will not contribute to Apdex calculations. | ## Results with "start" option [#start-results] 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. - The metric is dropped. |