Agent API guide template

Introduction: This section will introduce the agent and the API in general terms. Talk about when a user would want the API, and alternatives to using the API (for example, instrumentation via XML file). Mention that the API is often unnecessary if your framework has “out of the box” support. Link to the root of your API reference, whether that is on-site or off-site. Warn the user that they need to be on the most recent agent version.

Instrument missing sections of your code with transactions

To instrument your app, New Relic separates each path through your code into its own transaction. New Relic times (or “instruments”) the parent method in these transactions to measure your app’s overall performance, and collects transaction traces from long-running transactions for additional detail. For more information about transactions, see transaction and transaction trace.

Use these methods when New Relic is not instrumenting a particular part of your code at all:

If you want to...	Do this...
Start timing a method New Relic is not instrumenting automatically...	Create a new transaction. See [link to reference or tutorial doc for startTransaction() equivalent]
Stop timing a method after its work is completed...	Stop a transaction. See [link to reference or tutorial doc for stopTransaction() equivalent]
Prevent a transaction from reporting to New Relic...	Ignore the transaction. See [link to reference or tutorial doc for ignoreTransaction() equivalent]

Time specific methods using segments

If a transaction is already visible in the New Relic UI, but you don’t have enough data about a particular method that was called during that transaction, you can create segments to time those individual methods in greater detail. For example, you might want to time a particularly critical method with complex logic.

Use these methods when you want to instrument a method within an existing transaction:

If you want to...	Do this...
Time a particular method...	See [link to reference doc or tutorial doc for createTracer() equivalent].

Enhance the metadata of a transaction

Sometimes, the code you are targeting is visible in the New Relic UI, but some details of the method are not useful. For example, the default name might not be helpful (perhaps it is causing a metric grouping issue), or you want to add custom attributes to your transactions so you can better filter them when querying.

Use these methods when you want to change how New Relic instruments a transaction that’s already visible in the New Relic UI:

If you want to...	Do this...
Change the name of a transaction...	See [link to reference doc or tutorial doc for setTransactionName() equivalent].
Add metadata (such as your customer’s account name or subscription level) to your transactions...	Use custom attributes. See [link to reference doc or tutorial doc for addCustomParameter() equivalent].
Mark a transaction as a background job...	See [link to reference doc or tutorial doc for backgroundJob() equivalent].
Mark a transaction as a web transaction...	See [link to reference doc or tutorial doc for setRequestAndResponse() equivalent].
Prevent a transaction from affecting your [Apdex score]...	See [link to reference doc for ignoreApdex() equivalent].

Instrument asynchronous work

For supported frameworks, the agent usually detects async work and instruments it correctly. However, if your app uses another framework, or the default async instrumentation is inaccurate, you can explicitly connect async work using tokens and segments.

If you want to...	Do this...
Trace an async method that New Relic is already instrumenting...	See [link to tutorial doc].
Trace an async method that New Relic is not instrumenting...	See [link to tutorial doc].

Instrument calls to external services

Use these methods to collect data about your app’s connections to other apps or databases:

If you want to...	Do this...
Time a call to an external resource (such as an external service, database server, or message queue)...	Mark them as external after tracing them with [link to reference doc or tutorial doc for startTransaction() equivalent]. See [link to reference doc or tutorial doc for reportAsExternal() equivalent].
Connect activity to another app instrumented by a New Relic agent...	Use cross application tracing. See [link to reference doc or tutorial doc for addOutboundRequestHeaders() equivalent]
Time a custom transport channel, such as a proprietary RPC transport...	See [link to appropriate API methods or tutorial doc]

Collect or ignore errors

Usually, the agent detects errors automatically. However, you can manually mark an error with the agent. You can also mark errors as ignored or expected.

If you want to...	Do this...
Report an error the agent does not report automatically...	See [link to reference doc or tutorial doc for noticeError() equivalent].
Prevent the agent from reporting an error at all...	Mark the error as ignored. See [link to config doc or tutorial doc for ignore_classes equivalent].
Prevent an error from affecting your Apdex or error rate, but still report it to New Relic...	Mark the error as expected. See [link to config doc or tutorial doc for expected_classes equivalent].

Send custom event and metric data from your app

APM includes a number of ways to record arbitrary custom data. For an explanation of New Relic data types, see Data collection.

If you want to...	Do this...
Send data about an event so you can analyze it when querying...	Create a custom event. See [link to appropriate section of https://docs.newrelic.com/docs/insights/insights-data-sources/custom-dat... ]
Tag your events with metadata to filter/facet them when querying or when using error analytics...	Add custom attributes. See [link to reference or tutorial doc for addCustomAttribute() equivalent]
Report custom performance data once a minute...	Create a custom metric. See [link to reference or tutorial doc for recordMetric() equivalent]