New Relic collects and reports information on web browser transactions and background tasks. New Relic normally produces complete information right out of the box without any need to modify your application code. However, if New Relic does not support your framework, you may need to add custom instrumentation.
Custom instrumentation is also useful to:
- Add detail to your transaction traces.
- Block instrumentation on selected transactions you do not want instrumented.
- Instrument a part of your code that New Relic simply is not picking up.
Choosing custom instrumentation
Custom instrumentation allows you to track interactions that aren't captured by New Relic's automatic instrumentation. Custom instrumentation can also add detail to your transaction traces, to help you identify key issues.
New Relic collects data from many frameworks automatically. If you are using a supported framework, you should not need custom instrumentation to collect metric timeslices, events, and traces.
If you encounter one of these situations, you may need custom instrumentation:
- Transactions do not appear in the UI.
- Transaction traces include large blocks of application code time without full detail.
Implementing custom instrumentation
Each agent implements custom instrumentation differently:
- Go custom instrumentation
Because Golang apps run from a compiled, native binary file, all New Relic instrumentation must be done manually. See Instrument Go transactions and Instrument Go segments for how to set up instrumentation in your Go app.
- Java custom instrumentation
New Relic's Java agent supports two techniques for custom instrumentation:
- Annotation: Add @Trace annotations to your code to ensure New Relic instruments specific methods. Annotation is easy to implement, if you are instrumenting only a few methods. For more complex instrumentation, or if you are unable to modify your code, use XML.
- XML: Define the methods you want New Relic to monitor in an XML file. XML instrumentation is flexible and doesn't require editing your code, but is more difficult to troubleshoot than annotation.
For more information, see Java custom instrumentation.
- .NET custom instrumentation
New Relic's .NET agent defines custom instrumentation in extension files. You can define the assembly, class, and method names you want to trace by using one or more method tracers (tracerFactory).
New Relic reads every XML file in the extensions directory for custom instrumentation. You can use an XML-aware editor such as Visual Studio, and pair it with the companion file extension.xsd.
For more information, see .NET custom instrumentation.
- Node.js custom instrumentation
New Relic's Node.js agent uses API calls for custom instrumentation. For more information, see Node.js custom instrumentation.
- PHP custom instrumentation
New Relic's PHP agent uses API calls for custom instrumentation. For more information, see PHP custom instrumentation.
- Python custom instrumentation
New Relic's Python agent supports two techniques for custom instrumentation:
- Configuration file: Use the agent configuration file to specify the functions and methods you want instrumented. The agent configuration file is easy to set up, and it does not require you to modify your code. However, it is less flexible than API calls.
- API calls: Edit your code to call the New Relic Python API. The API is more flexible than instrumentation via the configuration file, but it requires you to modify your code.
For more information, see Python custom instrumentation.
- Ruby custom instrumentation
New Relic's Ruby agent uses API calls to define target methods and add transaction tracers to them. For more information, see Ruby custom instrumentation.
A metric grouping issue occurs when an account sends too many differently-named metric timeslices to New Relic, and those individual web transactions are not properly aggregated. For example, rather than a single
/user/controlpanel/ metric name, you might see
Custom instrumentation can cause metric grouping issues if you introduce too many uniquely-named metric timeslices that New Relic cannot effectively group. If you send thousands of metrics, New Relic may apply rules to reduce the number of transactions. For more information, see Metric grouping issues.
For more help
In addition to the agent documentation noted above, documentation resources for using custom instrumentation include: