Relic Solution: How to Custom Instrument Nearly Any Java Framework

We do our best to make sure the New Relic Java Agent supports as many frameworks as possible. New frameworks pop up every week, and we just can’t support them all. But you are a technology professional! As a technology professional, you assemble the right tools for the right job, even if that means using an unsupported Java framework. That’s ok! In this article, we’ll walk you through how you can use the Custom Instrumentation Editor to get the data you need.

Why Use the Custom Instrumentation Editor

It’s easier than you think! The Custom Instrumentation Editor allows you to instrument your application via the APM UI without having to make any code changes to get the reporting you need. Here are a few other benefits:

  • You are able to instrument many classes and methods being called in your application which are not base Java classes

  • Restart of your JVM is not normally required once the instrumentation is complete

  • The point and click interface ensures that the instrumentation just works. No guessing, misplaced or malformed code.

Get better metrics. You may be tempted to use URI-based naming in APM to get a really granular view of how your customers are interacting with your application. However, you will most likely only see a sliver of your data. APM cuts off metric reporting at a certain threshold, and URI-based metric naming can create dozens of metrics per customer, pushing up to that threshold pretty fast, and cutting you off from a lot of other valuable data.

Remember that APM is all about trends, and if APM can’t see all your metrics, it can’t tell you what direction your metrics are moving. If you really need to get a lot of granularity in your report, use Insights to query based on events or custom attributes, or use our Browser product to get URI-based metrics according to page views.

Avoid Metric Grouping Issues (MGIs). In addition to the incomplete view of your data that can occur when you choose to use URI-based naming in APM, it can also cause MGIs which increase your APM page load time, and mask app performance issues because important metrics are getting missed due to an inflation of URI-based metrics in your charts. When metric grouping issues become severe, to protect the databases from massive amounts of unhelpful data, New Relic can apply a transaction naming rule to your account that will simply map all URLs to a single web transaction name: /*.

If you ever notice all of your individual URLs disappearing and being replaced by/*, it means your account has had this metric limitation rule applied to it. An alert on the Transactions page will also notify you that limitation rules have been applied to your account.

How to Use the Custom Instrumentation Editor

To get started with the Custom Instrumentation Editor:

Also, please be aware that it is generally a good idea to check the “Start the transaction when this method executes” box during this instrumentation. The “Name the transaction” check box will simply RENAME the current transaction and should not be used except under circumstances where you specifically desire the transactions to be named using the previously un-instrumented classes and methods.

When your custom instrumented methods are called the agent looks for an existing transaction object to determine if the method was called as part of a transaction that is already being traced by the Java agent or if it is the start of a new transaction:

  • If there is a transaction object and the “Start the transaction…” box is checked, the custom instrumented method is included as part of the pre-existing transaction. Meaning the custom instrumented method won’t be reported as a new separate transaction.

  • If there is NO pre-existing transaction object and the “Start the transaction…” box is checked, the agent will create a new transaction for the custom instrumented method.

There is no way to force the agent to start a new transaction if the custom instrumented method is called as part of a pre-existing transaction.

Many thanks to @dmcmahon, @jkeller, and @Brent_Hara for their help with this article.