Known limitations with the New Relic Agent SDK


New Relic is focused on offering the many features that our other agents support, including transaction traces, traced errors, and key transactions. As such, we are aware of limitations with the New Relic Agent SDK that we have not been able to address yet. This document describes some of these known limitations, as well as recommended solutions as available.

Keep track of shared data (parent IDs)

In order to build a transaction trace, you need to provide information to the SDK about the relationships between segments. To accomplish this, your agent needs to pass parent IDs when starting new segments. Depending on your language, you might be able to take advantage of the SDK's auto-scoping feature.

Auto-scoping can be used to automatically identify the transaction ID and parent ID of a newly started segment. It works by keeping track of the last segment started within the current thread (using thread local storage). This is useful, for example, when a transaction runs uninterrupted from beginning to end within the same thread. For more information about threading considerations, see the threading section below.

If auto-scoping does not work, you will need to find a way to keep track of the current call stack. A simple way to do this is to keep a stack of segment IDs in memory. When a new segment starts, add it to the stack.; When a segment ends, remove it from the stack. The challenge then becomes one of identifying where to store the stack. Here are some options:

  • You can use a global web context object if your language supports it.
  • You can use thread local storage.
  • You can create a global map of running transactions.

Recommendation: For segments at the transaction's root, set the parent_segment_id to NEWRELIC_ROOT_SEGMENT.

Name transactions

Recommendation: Name the transactions based on their purpose, but use caution.

Issues arise when the granularity of the transaction name is too fine. This results in hundreds if not thousands of different transactions. If you name transactions poorly, your application may get blacklisted due to too many metrics being sent to New Relic.

A basic rule is to name transactions based on the controller action rather than the URL. For more information, see Metric grouping issues.

Threading considerations

Different languages support different threading models. Depending on the characteristics of your threading model, you will need to consider how your threads will interact with the SDK.

Threading scenarios Comments
Simple case In some languages, all segments of a transaction occur within the same thread. Additionally, a transaction will run from start to finish on the thread before another transaction begins on the same thread. This threading model is fully supported by the SDK.
Multiplexing Some languages are single threaded but can support multiple "simultaneous" transactions. In these languages, when a routine is blocked on I/O, it can be switched out in favor of a different routine on the same thread. The SDK should work in this scenario if you keep track of transaction IDs and parent IDs.
Multi-threading within a single transaction The SDK does not currently support segments occurring on different threads simultaneously within the same transaction. For more information, see thread safety.

Send events to Insights

Transaction events are not reported to Insights, and the SDK does not provide an API call to report custom events to Insights. You must insert custom events via the Insights API.

Known bugs

Known bugs in the New Relic Agent SDK are in the process of being fixed.

Settings page returns Error pages.

You will see an error page if you select Settings directly from Applications > (selected app). You will also see an error page if you select Settings > Application.

For more help

Troubleshoot and ask questions about the Agent SDK in New Relic's Online Technical Community!

If you need additional help, get support at