New Relic collects and reports information on web transactions and non-web transactions, such as background tasks. New Relic normally produces complete information automatically, without any need to modify your application code. However, if you are not using a supported 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.
Do not use brackets
[suffix] at the end of your transaction name. New Relic automatically strips brackets from the name. Instead, use parentheses
(suffix) or other symbols if needed.
When to use custom instrumentation
Custom instrumentation allows you to track interactions that are not 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.
However, if you encounter any 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.
Implement 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 methods of 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 supports two methods of custom instrumentation:
- Attributes: Annotate your code with agent API calls to instrument specific methods. Annotation is easy to implement, but requires editing your source code.
- XML: Define the methods you want New Relic to instrument in an XML file. XML instrumentation does not require modifying your source code, but is more complicated to create and keep updated than attribute instrumentation.
For more information, see Introduction to .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 methods of 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.