Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteChoose the Java agent’s @Trace API when you can edit the application and need to instrument a few methods. Choose XML when you cannot change the source or need to cover many methods. New Relic’s UI editor is another option for managed instrumentation changes; JMX is for monitoring MBeans, not tracing application methods.
Choose the right instrumentation method
| Method | Source edits | Best fit | Control and deployment | Restart and troubleshooting |
|---|---|---|---|---|
| Java API and annotations | Usually required | A small number of methods, or work requiring deeper API control | Instrumentation is declared in application code; the API also exposes static methods and API objects | Requires the API on the application classpath; confirm that tracing is enabled and inspect agent behavior if traces do not appear |
| XML extensions | Not required | Many methods or code that cannot be changed | XML files go in the agent’s extensions directory, or in the directory configured by common.extensions.dir |
The agent reads extensions at startup and checks the directory during harvest cycles; logging and pointcut matching can make troubleshooting more involved |
| Custom Instrumentation Editor | Not necessarily | Managed instrumentation edits through New Relic’s UI | Rules are managed in the UI, which also provides instrumentation history for Java apps | Use the history and agent logs to investigate changes and confirm what the agent applied |
| JMX | No application-method edits | Monitoring selected MBeans and their attributes | Configured separately through an external YAML file | YAML changes require restarting the JVM host process; JMX is not a substitute for tracing methods |
New Relic recommends annotations when you are willing to modify source code. Its guidance recommends XML when source cannot be changed or many methods need instrumentation. The Java agent API provides the broadest programmatic control; XML is simpler in that it does not require source changes, but it offers less API functionality.
Instrument a method with the Java API
Add the API and annotate the method
Annotation-based instrumentation normally requires newrelic-api.jar on the application’s classpath. With the agent’s custom tracing enabled, add @Trace to a method you want included in tracing:
import com.newrelic.api.agent.Trace;
public class ReportService {
@Trace
public Report buildReport() {
// Existing application work
return createReport();
}
}This adds the method to a trace; it does not by itself mean that the method should begin a new transaction. Use @Trace(dispatcher = true) when the method is the entry point for a new transaction, such as a background task:
#1 Best Overall
import com.newrelic.api.agent.Trace;
public class ReportJob {
@Trace(dispatcher = true)
public void run() {
// Background task work
}
}Use dispatcher tracing deliberately: it identifies a transaction entry point, rather than simply adding another method within an existing transaction. For asynchronous work that should remain connected to a parent transaction, use Java API support to link the child activity to its parent; adding a trace annotation alone may not establish that relationship.
Check the agent settings
The Java agent configuration defaults enable_custom_tracing to true. Confirm that the setting has not been disabled in your deployment. If you are instrumenting lambda expressions with @TraceLambda, enable instrumentation.trace_lambda.enabled explicitly. Lambda tracing is not implied by ordinary @Trace use.
Annotations are most maintainable when the method is stable and you control its source. If many methods need coverage, or the application cannot be rebuilt with the annotation and API dependency, use an extension instead.
Instrument methods with an XML extension
Place and name the extension
-
Create an XML extension and place it in the Java agent’s
extensionsdirectory. Alternatively, setcommon.extensions.dirinnewrelic.ymlto use a different directory.Recommended Free Tools
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Give each extension a unique name. If two extensions have the same name, the agent uses the one with the highest version.
-
Define only the pointcuts you need. XML can start transactions, match methods, match return types, or target lambdas. Validate the XML before deploying it, and follow New Relic’s extension format for the pointcut definition.
The extension is read at agent startup, and the agent checks the extensions directory during harvest cycles. As a result, a newly added file can be detected after startup without restarting the JVM. Allow for the harvest-cycle check, then look for the agent’s confirmation rather than assuming a file was applied immediately.
Keep pointcuts narrow
A pointcut that matches too broadly can add unwanted methods and create metric grouping issues. Avoid instrumenting every method. Narrow matching to the intended class and method, and use return-type matching or lambda targeting only when those are the actual methods you need to capture.
Use the Custom Instrumentation Editor for managed changes
The New Relic UI offers a Custom Instrumentation Editor for Java applications, along with instrumentation history. This is useful when you want to manage a rule through the UI rather than make an application-source change or distribute an XML extension yourself. Review the history when diagnosing a rule change, then compare the configured class and method with what the agent reports in its logs.
UI-managed instrumentation does not eliminate the need to verify matching. A rule that is saved but does not match the runtime class or method will not provide the intended trace data.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Verify that instrumentation loaded and matched
-
Check the selected method. Confirm that the configured class and method are the ones actually executed. The thread profiler can help identify instrumentable methods when you are unsure where to place instrumentation.
-
Check the extension file and location. For XML, confirm the file has an
.xmlextension and is in the agent extensions directory or the directory set bycommon.extensions.dir. Verify the XML before deployment.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Raise agent logging to
finer. For XML extensions, look for the log messageReading custom extension file. If a file was added after startup, account for the agent’s harvest-cycle directory check. -
Compare the pointcut with the log. Check that the class and method in the configuration correspond to the class and method the agent is loading. A file-read confirmation shows that the extension was read; it does not alone prove that the pointcut matched the method you intended.
-
Check the trace context. If a method is asynchronous, determine whether its activity should be a separate transaction or a child of an existing one. Use the Java API where needed to connect child activity to its parent.
When JMX is the right alternative
Use JMX when the goal is to collect selected MBean attributes, not to add spans or transactions around application methods. JMX configuration is a separate external YAML file: its keys are case-sensitive, indentation must use two spaces, and a change requires restarting the JVM host process. Do not apply the XML extension refresh behavior to JMX configuration.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsVersion note for OpenTelemetry compatibility
New Relic documents OpenTelemetry Tracing, Metrics, and Logs API compatibility beginning with Java agent version 9.1.0. That version detail concerns API compatibility; it does not change the decision between annotation-based custom tracing and XML pointcuts for New Relic Java agent instrumentation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
