---
title: Java serverless AWS Lambda performance monitoring
source: https://docs.newrelic.com/docs/apm/agents/java-agent/getting-started/java-agent-approaches-lambda
---

You can gain visibility into your Java Lambda functions to understand what's happening in your serverless applications.

> #### ⚠️ IMPORTANT
>
> This doc details how to use the new APM agent based solution for Java Serverless monitoring. This solution was released on April 10, 2026.
> Users who were using Java Monitoring prior to this release or are using Java versions 11 or 8 should instead use our [Legacy Open Tracing Based Java solution](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/instrument-your-own/#console).

## New Relic Java agent [#java-agent]

The New Relic Java agent supports instrumenting AWS Lambda functions through a dedicated **serverless mode**. When running inside a Lambda function, the agent automatically detects the environment and switches into this mode, which is optimized for the short-lived, event-driven nature of Lambda invocations.

> #### ⚠️ IMPORTANT
>
> Java agent serverless mode requires **Java 17 or later**. Java 11 and older runtimes aren't supported due to longer initial startup times.

### How it works

In serverless mode, the agent replaces its standard periodic harvest and HTTP transport with a per-invocation model:

1.  When a Lambda function is invoked, the agent intercepts the handler before your code runs.
2.  A transaction is created automatically for the invocation, capturing context like the Lambda ARN, request ID, and whether this is a cold start.
3.  If the event payload is recognized (for example, an API Gateway or SQS event), the agent extracts event-source metadata, classifies the transaction as a web or non-web transaction, and adds relevant attributes.
4.  When the transaction finishes, the agent collects all buffered telemetry and writes it as a compressed, Base64-encoded payload to `/tmp/newrelic-telemetry` and as plain JSON to stdout.
5.  The [New Relic Lambda Extension](https://github.com/newrelic/newrelic-lambda-extension/tree/main) (bundled in the layer) reads the telemetry file and forwards the data to New Relic after each invocation.

### Lambda layers [#layers]

Two Lambda layer variants are published for the Java agent:

-   **Full agent layer**: all instrumentation modules are enabled. Provides maximum out-of-the-box visibility, but incurs higher cold start overhead due to the full set of auto-instrumentation.
-   **Slim layer (recommended)**: disables all auto-instrumentation _except_ the `aws-lambda-java-core` modules. This means Java Lambda handlers that implement `RequestHandler` or `RequestStreamHandler` are automatically instrumented and begin emitting telemetry out of the box, while other instrumentation (AWS SDK calls, HTTP clients, etc.) is disabled unless you explicitly opt in. This is the recommended starting point for most customers.

### Layer ARNs [#layer-arns]

The following ARNs are for the `us-east-1` region. Replace `us-east-1` with your AWS region. The layer version starts at `1` and increments with each new release. For the latest available versions, see [New Relic's layer list](https://layers.newrelic-external.com/).

| Layer variant      | Architecture | ARN                                                                         |
| ------------------ | ------------ | --------------------------------------------------------------------------- |
| Slim (recommended) | x86_64       | `arn:aws:lambda:us-east-1:451483290750:layer:NewRelicAgentJava-slim:1`      |
| Slim (recommended) | ARM64        | `arn:aws:lambda:us-east-1:451483290750:layer:NewRelicAgentJavaARM64-slim:1` |
| Full               | x86_64       | `arn:aws:lambda:us-east-1:451483290750:layer:NewRelicAgentJava:1`           |
| Full               | ARM64        | `arn:aws:lambda:us-east-1:451483290750:layer:NewRelicAgentJavaARM64:1`      |

For installation instructions, see [Layered instrumentation](https://docs.newrelic.com/docs/serverless-function-monitoring/aws-lambda-monitoring/instrument-lambda-function/instrument-your-own/).

When using either layer, set your Lambda function's handler to one of the following wrapper values so the agent can intercept the invocation:

-   `RequestHandler` implementation: `com.newrelic.java.HandlerWrapper::handleRequest`
-   `RequestStreamHandler` implementation: `com.newrelic.java.HandlerWrapper::handleStreamsRequest`

### Automatic detection

The agent automatically enables serverless mode when the `AWS_LAMBDA_FUNCTION_NAME` environment variable is present. No explicit configuration is required when using the Lambda layer. Serverless mode is always enabled and can't be overwritten.

### Configuration [#configuration]

The following environment variables are pre-configured in the Lambda layer:

| Environment variable                               | Layer default     | Description                                                                                                                                           |
| -------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEW_RELIC_SERVERLESS_MODE_ENABLED`                | `true`            | Enables serverless mode. Set to `true` by the layer if not already defined.                                                                           |
| `NEW_RELIC_LOG_FILE_PATH`                          | `/tmp/logs`       | By default, this sets the Java agent log file path to `/tmp/logs/newrelic_agent.log`                                                                  |
| `NEW_RELIC_APP_NAME`                               | `lambda-function` | Default application name used by the agent. Set by the layer if not already defined. This value is not used in the New Relic UI for Lambda functions. |
| `NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED` | `false`           | Disables in-agent log forwarding. Set by the layer if not already defined. Logs are captured via CloudWatch or the Lambda extension instead.          |
| `NEW_RELIC_ENABLE_AUTO_APP_NAMING`                 | `false`           | Always set to `false` by the layer. Prevents the agent from overriding the application name based on transaction data.                                |

The following environment variables are required and must be set by you:

| Environment variable            | Required value               | Description                                                                                                                                                   |
| ------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWS_LAMBDA_EXEC_WRAPPER`       | `/opt/newrelic-java-handler` | Points AWS Lambda to the New Relic Java agent wrapper. This must always be set to `/opt/newrelic-java-handler` when using the Java agent layer.               |
| `NEW_RELIC_LICENSE_KEY`         | Your New Relic license key   | Your New Relic ingest license key, used to authenticate telemetry sent to New Relic.                                                                          |
| `NEW_RELIC_TRUSTED_ACCOUNT_KEY` | Your New Relic account ID    | Required by the New Relic Lambda extension for distributed tracing. Set this to your New Relic parent account ID or account ID if there is no parent account. |

> #### ⚠️ IMPORTANT
>
> By default, the Lambda extension or CloudWatch captures your logs. The agent doesn't forward logs directly.

### Cold starts [#cold-starts]

The agent tracks cold starts using a static flag that's set on the first invocation. On cold start invocations, the `aws.lambda.coldStart=true` attribute is added to the transaction. This attribute is omitted on warm invocations. It isn't set to `false`.

> #### ⚠️ IMPORTANT
>
> **Cold start time**: Adding the Java agent increases cold start time by approximately 4,000–6,200 ms compared to a function without the agent. This only affects the first invocation. Warm invocations aren't affected. The slim layer reduces this by loading fewer monitoring modules at startup.
>
> To improve cold start performance, increase the timeout threshold and memory allocation, and use provisioned concurrency.

### Telemetry collected [#telemetry]

In serverless mode, the Java agent collects and buffers the following telemetry types during invocation:

-   Transaction traces
-   Error events and traced errors (with stack traces)
-   Span events (for distributed tracing)
-   Transaction (analytic) events
-   Custom events
-   Log events (via CloudWatch by default)
-   Performance metrics

All collected data is written as a single `NR_LAMBDA_MONITORING` payload and forwarded to New Relic after the invocation completes.

### Limitations [#limitations]

-   **Java 17+ only.** Java 11 and earlier are not supported.
-   Thread profiling is not available in serverless mode.
-   JFR (Java Flight Recorder) monitoring is disabled in serverless mode.
-   The JAR collector (module scanning) is disabled in serverless mode.