---
title: Guide to using the Java agent API 
source: https://docs.newrelic.com/docs/apm/agents/java-agent/api-guides/guide-using-java-agent-api
---

The New Relic Java agent API lets you control, customize, and extend the functionality of the APM [Java agent](https://docs.newrelic.com/docs/agents/java-agent/getting-started/new-relic-java). This API consists of:

-   Static methods on the `com.newrelic.api.agent.NewRelic` class
-   A [`@Trace` annotation](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-annotation) for implementing custom instrumentation
-   A hierarchy of API objects providing additional functionality

Use this API to set up [custom instrumentation](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-custom-instrumentation) of your Java app and collect more in-depth data. For detailed information about this API, see the complete [Javadoc on GitHub](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html).

Another way to set up custom instrumentation is to use [XML instrumentation](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-xml). The XML option is simpler and does not require modification of your app code, but it lacks the complete functionality of the Java agent API.

> #### ⚠️ IMPORTANT
>
> For best results when using the API, ensure that you have the [latest Java agent release](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes). Several APIs used in the examples require Java agent 6.4.0 or higher.

For all available New Relic APIs, see [Intro to APIs](https://docs.newrelic.com/docs/apis/getting-started/introduction-new-relic-apis).

## Use the API [#api]

To access the API, download it from maven central via a build tool.

Here's an example for gradle where you can replace `${agent.version}` with version of your agent:

```groovy
implementation 'com.newrelic.agent.java:newrelic-api:${agent.version}'
```

You can call the API even without the agent running, but the methods will be a no-op until the agent loads your application.

## Transactions

To instrument [transactions](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/transactions-page) in your application, use the following APIs.

| If you want to...                                                                                                                                                                          | Use this                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create a `Transaction` when New Relic does not create one automatically                                                                                                                    | [`@Trace(dispatcher = true)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Trace.html) on the method that encompasses the work to be reported. When this annotation is used on a method within the context of an existing transaction, this will not start a new transaction, but rather include the method in the existing transaction. |
| Capture the duration of a method that New Relic does not automatically trace                                                                                                               | [`@Trace()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Trace.html) on the method you want to time.                                                                                                                                                                                                                                    |
| Set the name of the current `Transaction`                                                                                                                                                  | [`NewRelic.setTransactionName(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                         |
| Start the timer for the response time of the current `Transaction` and to cause a `Transaction` you create to be reported as a `Web` transaction, rather than as an `Other` transaction    | [`NewRelic.setRequestAndReponse(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                       |
| Add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes) to `Transactions` and `TransactionEvents`                            | [`NewRelic.addCustomParameter(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                         |
| Adds [user tracking](https://docs.newrelic.com/docs/apm/agents/java-agent/attributes/java-agent-attributes#user-attributes) to `Transactions` by setting the `enduser.id` agent attribute. | [`NewRelic.setUserId()`](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                                      |
| Prevent a `Transaction` from being reported to New Relic                                                                                                                                   | [`NewRelic.ignoreTransaction()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                             |
| Exclude a `Transaction` when calculating your app's [Apdex](https://docs.newrelic.com/docs/apm/new-relic-apm/apdex/apdex-measuring-user-satisfaction) score                                | [`NewRelic.ignoreApdex()`](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                                    |

## See related logs [#logs]

To see logs directly within the context of your application's errors and traces, use these API calls to annotate your logs:

-   [`getTraceMetadata`](http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/Agent.html#getTraceMetadata())
-   [`getLinkingMetadata`](http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/Agent.html#getLinkingMetadata())

For more information about correlating log data with other telemetry data, see our [logs in context](https://docs.newrelic.com/docs/logs/logs-context/java-configure-logs-context-all/) documentation.

## Instrument asynchronous work [#async]

For detailed information, see [Java agent API for asynchronous applications](https://docs.newrelic.com/docs/agents/java-agent/async-instrumentation/java-agent-api-asynchronous-applications).

| If you want to...                                                                      | Use this                                                                                                                                   |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Trace an asynchronous method if it is linked to an existing `Transaction`...           | [`@Trace(async = true)`](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                 |
| Link the `Transaction` associated with the `Token` on the current thread...            | [`Token.link()` or `Token.linkAndExpire()`](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Token.html) |
| Expire a `Token` associated with the current `Transaction`...                          | [`Token.expire()`](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Token.html)                          |
| Stop timing a `Segment` and have it report as part of its parent `Transaction`         | [`Segment.end()`](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Segment.html)                         |
| Stop timing a `Segment` and **not** have it report as part of its parent `Transaction` | [`Segment.ignore()`](http://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Segment.html)                      |

## Distributed tracing API usage [#trace-calls]

These APIs require [distributed tracing to be enabled](https://docs.newrelic.com/docs/enable-distributed-tracing). See [Java agent configuration](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#distributed-tracing) for all distributed tracing config options.

Distributed tracing lets you see the path that a request takes as it travels through a distributed system. For general instructions on how to use the calls below to implement distributed tracing, see [Use distributed tracing APIs](https://docs.newrelic.com/docs/enable-distributed-tracing#agent-apis). To see these APIs in action, see [Using Java agent distributing tracing API with Kafka](https://github.com/newrelic/newrelic-java-examples/tree/main/newrelic-java-agent/distributed-tracing/kafka-examples).

> #### ⚠️ IMPORTANT
>
> With [agent version 6.4.0](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes/java-agent-640), the following distributed tracing APIs were introduced, with the exception of `addCustomAttribute()`, which was introduced in 6.1.0. We highly recommended using these APIs instead of the [deprecated ones](#deprecated-trace-apis).

| If you want to...                                                                                                                                                                                                                                                                                                                                                                            | Use this                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Learn about the type-specific headers of an inbound or outbound message.                                                                                                                                                                                                                                                                                                                     | ```` <a href="http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/Headers.html">Headers</a> ```  For a provided implementation of `Headers` use `ConcurrentHashMapHeaders`.  See an example of W3C trace context headers implementation in [DT API usage with Kafka](https://github.com/newrelic/newrelic-java-examples/tree/main/newrelic-java-agent/distributed-tracing/kafka-examples).  ```` |
| Create and insert distributed tracing headers into a `Headers` data structure. This API will insert both `newrelic` and W3C Trace Context headers (`traceparent` & `tracestate`), unless the agent is explicitly [configured to exclude `newrelic` headers](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file#dt-exclude_newrelic_header). | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html">Transaction.insertDistributedTraceHeaders(Headers)</a> ```  For more on obtaining references to the current transaction and other API classes, see [Obtain references](#obtain-references).  ````                                                                                                |
| Accept the distributed tracing headers sent from the calling service and link these services together in a distributed trace.                                                                                                                                                                                                                                                                | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html">Transaction.acceptDistributedTraceHeaders(TransportType, Headers)</a> ```  For more on obtaining references to the current transaction and other API classes, see [Obtain references](#obtain-references).  ````                                                                                 |
| Understand a utility class that provides enum constants for defining the transport type when accepting distributed tracing headers.                                                                                                                                                                                                                                                          | ```` <a href="http://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/TransportType.html">TransportType</a> ```  ````                                                                                                                                                                                                                                                                                |
| Add [custom attributes](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-custom-attributes) to `SpanEvents` in distributed traces                                                                                                                                                                                                                                  | [`NewRelic.getAgent().getTracedMethod().addCustomAttribute(...)`](https://newrelic.github.io/java-agent-api/javadoc/com/newrelic/api/agent/TracedMethod.html)                                                                                                                                                                                                                                                        |

> #### ⚠️ CAUTION
>
> With [agent version 6.4.0](https://docs.newrelic.com/docs/release-notes/agent-release-notes/java-release-notes/java-agent-640), the following distributed tracing APIs have been deprecated and replaced by the APIs in the above table. It's highly recommended to upgrade the agent and use the new APIs instead of these deprecated ones.

| If you want to...                                                                                                           | Use this                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create a payload to be sent to a called service.                                                                            | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html">Transaction.createDistributedTracePayload()</a> ```  For more on obtaining references to the current transaction and other API classes, see [Obtain references](#obtain-references).  <Callout variant="caution">   API deprecated as of agent 6.4.0 </Callout>  ````    |
| Accept a payload sent from the first service; this will link these services together in a trace.                            | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html">Transaction.acceptDistributedTracePayload(...)</a> ```  For more on obtaining references to the current transaction and other API classes, see [Obtain references](#obtain-references).  <Callout variant="caution">   API deprecated as of agent 6.4.0 </Callout>  ```` |
| Payload used to connect services. The `text()` call returns a JSON string representation of the payload.                    | `DistributedTracePayload.text()` > #### ⚠️ CAUTION > > API deprecated as of agent 6.4.0                                                                                                                                                                                                                                                                                                      |
| Payload used to connect services. The `httpSafe()` call returns a base64 encoded JSON string representation of the payload. | `DistributedTracePayload.httpSafe()` > #### ⚠️ CAUTION > > API deprecated as of agent 6.4.0                                                                                                                                                                                                                                                                                                  |

## Cross application tracing (CAT) API usage [#trace-calls-cat]

> #### ⚠️ IMPORTANT
>
> Cross application tracing has been deprecated as of agent version 7.4.0 and will be removed in a future agent version.
>
> Instead of using cross application tracing, we recommend our [distributed tracing](#distributed-tracing) features. Distributed tracing is an improvement on the cross application tracing feature and is recommended for large, distributed systems.

To track external calls and add [cross application tracing](https://docs.newrelic.com/docs/apm/transactions/cross-application-traces/cross-application-tracing), use the following APIs:

| If you want to...                                                                                                                                                                                                                                                                    | Use this                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Trace across a custom transport channel that New Relic does not support by default, such as a proprietary RPC transport                                                                                                                                                              | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html">Transaction.getRequestMetadata(), .processRequestMetadata(...), .getResponseMetadata(), .processResponseMetadata(...)</a> ```  Also refer to the information in this document about using `Transaction` to [obtain references to New Relic API classes](#).  ````                                                                        |
| View or change the metric name or a rollup metric name of a `TracedMethod` (A rollup metric name, such as `OtherTransaction/all`, is not scoped to a specific transaction. It represents all background transactions.)                                                               | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/TracedMethod.html">TracedMethod.getMetricName(), .setMetricName(...), .setRollupMetricName(...)</a> ```  Also refer to the information in this document about using `TracedMethod` to [obtain references to New Relic API classes](#).  ````                                                                                                               |
| Report a call to an external HTTP service, database server, message queue, or other external resource that is being traced using the Java agent API's [`@Trace` annotation](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-annotation) | [`TracedMethod.reportAsExternal(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/TracedMethod.html) passing arguments constructed using [`ExternalParameters`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/ExternalParameters.html) builder. Also refer to the information in this document about using `TracedMethod` to [obtain references to New Relic API classes](#). |
| Enable and add [cross application tracing](https://docs.newrelic.com/docs/apm/transactions/cross-application-traces/cross-application-tracing) when communicating with an external HTTP or JMS service that is instrumented by New Relic                                             | [`TracedMethod.addOutboundRequestHeaders(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/TracedMethod.html) along with `TracedMethod.reportAsExternal(...)` Also refer to the information in this document about using `TracedMethod` to [obtain references to New Relic API classes](#).                                                                                                                         |
| Add timing for an application server or dispatcher that is not supported automatically                                                                                                                                                                                               | `Transaction.setRequest(...), Transaction.setResponse(...)`, or `NewRelic.setRequestAndResponse(...)`, and `Transaction.markResponseSent()` Also refer to the information in this document about using `Transaction` to [obtain references to New Relic API classes](#).                                                                                                                                                                                     |

## Obtain references to New Relic API classes [#obtain-references]

Other tasks require the New Relic `Agent` object. The `Agent` object exposes multiple objects that give you the following functionality:

| If you want to...                                                                                                                                                                                                                                       | Use this                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get a reference to the current `Transaction`                                                                                                                                                                                                            | [`NewRelic.getAgent().getTransaction()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html)                                        |
| Get a `Token` to link asynchronous work                                                                                                                                                                                                                 | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html">NewRelic.getAgent().getTransaction().getToken()</a> ```  ````     |
| Start and get a reference to a `Segment`                                                                                                                                                                                                                | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Transaction.html">NewRelic.getAgent().getTransaction().startSegment()</a> ```  ```` |
| Get a reference to the method currently being traced                                                                                                                                                                                                    | [`NewRelic.getAgent().getTracedMethod()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/TracedMethod.html)                                      |
| Get a reference to the `Agent` logger                                                                                                                                                                                                                   | [`NewRelic.getAgent().getLogger()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Logger.html)                                                  |
| Get a reference to the `Agent` [configuration](https://docs.newrelic.com/docs/agents/java-agent/configuration/java-agent-configuration-config-file)                                                                                                     | [`NewRelic.getAgent().getConfig()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Config.html)                                                  |
| Get a reference to an aggregator for [custom metrics](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics)                                                                                                                | [`NewRelic.getAgent().getAggregator()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/MetricAggregator.html)                                    |
| Get a reference to `Insights` (our original name for the feature that governed custom events) in order to record [custom events](https://docs.newrelic.com/docs/insights/new-relic-insights/custom-events/inserting-custom-events-new-relic-apm-agents) | [`NewRelic.getAgent().getInsights()`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/Insights.html)                                              |

## Additional API functionality [#additional]

The following APIs provide additional functionality, such as setting app server info, reporting errors, adding [page load timing](https://docs.newrelic.com/docs/agents/java-agent/instrumentation/page-load-timing-java) information, recording [custom metrics](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics), and [sending custom events](https://docs.newrelic.com/docs/insights/new-relic-insights/custom-events/inserting-custom-events-new-relic-apm-agents).

| If you want to...                                                                                                                                                                                                                                                                                                                                                                                  | Use this                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Explicitly set port, name, and version information for an application server or dispatcher and the instance name for a JVM                                                                                                                                                                                                                                                                         | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html">NewRelic.setAppServerPort(...), .setServerInfo(...), and .setInstanceName(...)</a> ```  ````                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Report an error that New Relic does not report automatically                                                                                                                                                                                                                                                                                                                                       | [`NewRelic.noticeError(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html) When inside a transaction, the last call to `noticeError` wins. Only 1 error will be reported per transaction.                                                                                                                                                                                                                                                                                                                                                                                                       |
| Group errors with your own custom defined fingerprint, implement the [`ErrorGroupCallback`](https://docs.newrelic.com/docs/apm/agents/java-agent/api-guides/java-agent-api-register-error-group-callback-to-set-fingerprint) interface are used to generate grouping keys for errors that will be sent to New Relic.  The fingerprint will be used to group error messages in the Errors Inbox UI. | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html">public interface ErrorGroupCallback {     String generateGroupingString(ErrorData errorData); }()</a> ```  ````                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Set your own error fingerprint via a callback function. To register an [`ErrorGroupCallback`](https://docs.newrelic.com/docs/apm/agents/java-agent/api-guides/java-agent-api-register-error-group-callback-to-set-fingerprint) that's used to generate a grouping key for the supplied error.                                                                                                      | [`NewRelic.setErrorGroupCallback(errorGroupCallback)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Add browser [page load timing](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-agent-api-example-program#include-browser) for `Transactions` that New Relic does not add to the header automatically                                                                                                                                                                  | ```` <a href="https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html">NewRelic.getBrowserTimingHeader(), .getBrowserTimingFooter(), .setUserName(String name), .setAccountName(String name), and .setProductName(String name)</a> ```  ````                                                                                                                                                                                                                                                                                                                                                                |
| Create and accumulate [custom metrics](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/custom-metrics)                                                                                                                                                                                                                                                                          | [`NewRelic.recordMetric(...)`, `.recordResponseTimeMetric(...)`, or `.incrementCounter(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Record [custom events](https://docs.newrelic.com/docs/insights/new-relic-insights/custom-events/inserting-custom-events-new-relic-apm-agents)                                                                                                                                                                                                                                                      | `Insights.recordCustomEvent(...)` Or, use [`NewRelic.addCustomParameter(...)`](https://newrelic.github.io/java-agent-api/javadoc/index.html?com/newrelic/api/agent/NewRelic.html) to add custom attributes to the New Relic-defined `TransactionEvent` type. Also refer to the information in this document about using `Insights` to [obtain references to New Relic API classes](#).                                                                                                                                                                                                                                                                |
| Provide general cloud provider account information to the agent                                                                                                                                                                                                                                                                                                                                    | ````java NewRelic.getAgent().getCloud().setAccountInfo(CloudAccountInfo.AWS_ACCOUNT_ID, "..."); ```  With this method, you can provide the type of account information and its value. The agent uses this information to populate the attribute `cloud.resource_id` in the select cloud services spans.  AWS DynamoDB and Kinesis are services that require this value to populate the `cloud.resource_id` attribute. Similarly, AWS Lambda requires this value when the account ID is not part of the function name.  Calling this method overrides the respective cloud configuration. The call shown above overrides `cloud.aws.account_id`.  ```` |
| Provide SDK client specific cloud provider account information to the agent                                                                                                                                                                                                                                                                                                                        | ````java NewRelic.getAgent().getCloud().setAccountInfo(sdkClient, CloudAccountInfo.AWS_ACCOUNT_ID, "..."); ```  This call provides the same information as the preceding method, but it is specific to the SDK client provided. When the specified SDK client is used, this data will be used instead of the general one.  ````                                                                                                                                                                                                                                                                                                                       |

## Additional API usage examples [#api-examples]

For detailed code examples about using the APIs, see New Relic's documentation about custom instrumentation for:

-   [External calls, cross application traces, messaging, datastores, and web frameworks](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-agent-api-overview-custom-instrumentation-external-calls-cat-messaging-datastore-web-frameworks)
-   [Cross application tracing and external datastore calls](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-agent-api-example-application-using-custom-instrumentation-cross-application-tracing-cat)
-   [Apps using custom instrumentation with annotation](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-agent-api-example-program)
-   [Custom framework instrumentation API](https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-agent-instrumentation-api)
-   [Preventing unwanted instrumentation](https://docs.newrelic.com/docs/agents/java-agent/instrumentation/blocking-instrumentation-java)
-   [Inserting custom attributes](https://docs.newrelic.com/docs/data-analysis/metrics/collecting-custom-attributes#java-att)
-   [Inserting custom events](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/inserting-custom-events-new-relic-apm-agents#java-att)
-   [Collecting custom metrics](https://docs.newrelic.com/docs/apm/other-features/metrics/custom-metrics)