--- title: Java instrumentation by XML source: https://docs.newrelic.com/docs/apm/agents/java-agent/custom-instrumentation/java-instrumentation-xml --- For your New Relic-monitored Java application, one custom instrumentation method is to use an XML file to specify your app methods that should be instrumented. The Java agent will read the XML file and instrument the relevant classes on startup; XML files added to the [`extensions` directory](#file-location) after startup do not require a JVM restart to be detected. See [Java agent custom instrumentation](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-custom-instrumentation) for a description of the custom instrumentation options and the reasons to use them. ## Accessing your XML file [#ui-options] Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > APM & services > (select an app) > Settings > Instrumentation**. From here you can: - Download a sample XML file. (You can do this from the pop-up that appears when you click `Import an XML file`.) - Select an edit existing XML file. - Search the instrumentation history. ## XML file structure [#file-structure] Your New Relic agent download package (`newrelic_agent.zip`) contains two templates for using XML instrumentation: - The `extension.xsd` template is the XML schema definition which all custom extensions must follow. - The `extension-example.xml` template is an example. This file instruments some of the basic JDK methods. If you edit and rename this file, ensure you modify the `name="extension-example"` attribute to match the new filename. For more information about the properties in the `extension.xsd` template, see the [XML file format overview](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-custom-instrumentation-xml-examples#file-format). ## XML file validation [#file-validation] Before starting your application, validate your XML file using New Relic's command line tool. The command line tool can only be used when your classes are in a jar. There are two ways to validate your XML instrumentation: **Java versions below Java 10** The easiest way to do this for Java versions lower than Java 10 is with this command: ````bash java -Djava.ext.dirs=/path/to/jarred/classes -jar newrelic.jar instrument -file /path/to/file.xml -debug true ``` ```` **All Java versions** > #### 💡 TIP > > For Java versions below Java 10, see the [recommended procedure](#pre-java-10). That procedure is not possible with Java 10 or higher because those versions no longer allow `java.ext.dirs` to be set. For all Java versions, you can set the `classpath` manually: ````bash java -cp /path/to/your-app.jar:/path/to/newrelic.jar com.newrelic.bootstrap.BootstrapAgent instrument -file /path/to/file.xml -debug true ``` ```` The application is run with the `newrelic.jar`. The call must contain the keyword `instrument` followed by the `-file` flag with the path to your XML file. The property `-debug` is optional and may be set to `true` to provide more information during the validation. The tool will: - Validate the XML syntax. - Check that each class to be instrumented is present on the class path. - Check that each method is contained in the appropriate class. If the XML file is valid, you will see a pass statement printed to the terminal: ``` PASS: The extension at file.txt was successfully validated. ``` If the XML fails validation, you will see a failure message printed to the terminal: ``` FAIL: reason ``` ## XML file location [#file-location] The Java agent reads any XML files in the `extensions` directory on process start up. The `extensions` directory is also read every [harvest cycle](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#harvest-cycle). XML files added to this directory during runtime will be read within a few minutes, so they do not require a JVM restart. There are two ways to specify the XML file location: | **XML file location options** | **Procedure** | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create an extensions directory | - In the directory where the newrelic.jar and newrelic.yml is located, create a directory named `extensions`. - Put the XML file in this directory with a `.xml` extension. - In `newrelic.yml`, check that the property `extensions.dir` is not set. | | Specify an existing extensions directory | - In the `newrelic.yml` configuration file under the common section, use the property `extensions.dir` to specify the directory where the XML file is located. - Make sure the file is in the specified directory and that the file has a `.xml` extension. | ## Verify the file was read [#verifying-read] To verify the agent read the XML file, first [set the Log management to `finer`](https://docs.newrelic.com/docs/java/java-kb-101): 1. Edit the `newrelic.yml` configuration file and change the `log_level` property: ```yml log_level: finer ``` 2. Start or restart the application. If the read was successful, `logs/newrelic_agent.log` will indicate this in a statement similar to: ``` Reading custom extension file /path/to/file.xml ``` If no statement appears in `logs/newrelic_agent.log`, then the XML file was not found. Check the location of the XML file, and ensure the New Relic process has read access to the file. ## Multiple XML files [#multiplying-files] While using a single XML file is preferred, you can use multiple custom XML files. These files will all be instrumented as long as the extension name in the files is unique. - If two custom XML files contain the same extension name, then the one with the highest version will be implemented and the other will be ignored. - If the two files have the same name and version, then the first file read by the agent will be implemented and the other will be ignored. ## XML and YAML Prior to 2.10.0, YAML files could be used for custom instrumentation. These legacy YAML files are still supported. However, new users should use XML files for custom instrumentation. **Legacy users:** If both a YAML and XML file exist with the same extension name, only the XML file will be instrumented. The YAML file will be ignored. If you want both the YAML and XML files to be instrumented, give each file a different extension name. ## Example XML file [#example] For an example of a custom instrumentation XML file, see [Java XML examples](https://docs.newrelic.com/docs/java/custom-xml-examples).