Transaction naming protocol

If you're using New Relic for Java with a supported framework, New Relic groups transactions based on transaction names obtained from the framework. Otherwise, New Relic groups transactions based on their component. Components are the JSPs, servlets, and filters invoked during the transaction.

Grouping transactions

The New Relic Java agent groups similar transactions together under a single name. If New Relic did not group transactions, each unique URI would generate a unique name. For example, your web application might produce URIs like:

/user/123/control_panel.jhtml
/user/456/control_panel.jhtml
/user/789/control_panel.jhtml

Without grouping, this would produce three (fairly meaningless) individual metrics. Therefore, New Relic attempts to group transactions together under a meaningful label. For more information about metric grouping, see Metric grouping issues.

Transaction names use URI format. For example:

MyTransactionName
/MyTransactionName
/MyServlet/MyTransactionName

If you are using a supported framework, New Relic obtains the transaction name from the framework. For example, for Spring the transaction name typically comes from calling getViewName on the org.springframework.web.servlet.ModelAndView object.

If you are not using a supported framework, New Relic names a transaction based on its components. The exact transaction name is determined by the component with the highest priority. If multiple component share priority, the agent uses the first component that was invoked.

Naming priority

New Relic assigns each transaction a name according to the following priority, from highest priority to lowest:

Request attributes

Request attributes and API calls have the highest naming priority. If a transaction has a request attribute or API call, the transaction will take its name from there.

You can set the request attribute at any time during the web request. If you set multiple attributes during a request, the most recent name will be used.

This example sets the transaction name using a request attribute in a servlet's doGet:

protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
    ...
    request.setAttribute("com.newrelic.agent.TRANSACTION_NAME", "MyTransactionName");
    ...
}

API Calls

You can also set the transaction name by calling the setTransactionName method from the Java agent API. An API call has the same priority as a request attribute. If you set multiple attributes or make multiple API calls during a request, the most recent name will be used.

Frameworks

If there are no request attributes or API calls, and you're using a supported framework, New Relic obtains the transaction name from the framework components.

JavaServer Pages (JSPs)

After frameworks, the New Relic Java agent will use JavaServer Pages (JSPs). A JSP gets the transaction name from its class name. For example, if the JSP servlet class name is org.apache.jsp.ShowBrowser_jsp the transaction name is ShowBrowser.jsp.

Servlets

After JSPs, the New Relic Java agent will use servlets. A servlet sets the transaction name from either an init parameter or the servlet name. The init parameter is higher priority, so servlets with an init parameter take precedence over servlets without.

The servlet name and init parameter are defined in the deployment descriptor. For example:

SqlServlet test.SqlServlet com.newrelic.agent.TRANSACTION_NAME MyTransactionName

Servlet filters

Servlet filters have the lowest priority. A filter gets the transaction name either from an init parameter or the filter name. The init parameter has a higher priority, so filters with an init parameter take precedence over filters without.

The filter name and init parameter are defined in the deployment descriptor. For example:

SqlFilter test.SqlFilter com.newrelic.agent.TRANSACTION_NAME MyTransactionName

The filter name is the value of the filter-name element. The init parameter is the value of the param-value element of an init-param element with a param-name element of com.newrelic.agent.TRANSACTION_NAME.

Disable component-based naming

For some applications, you may want to disable component-based transaction naming. Set this value in your newrelic.yml file:

enable_auto_transaction_naming: false

For more help