Java serverless AWS Lambda performance monitoring

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

You can use the slim layer Java agent variation to gain visibility into your Java Lambda functions.

New Relic 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.

중요

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:

When a Lambda function is invoked, the agent intercepts the handler before your code runs.
A transaction is created automatically for the invocation, capturing context like the Lambda ARN, request ID, and whether this is a cold start.
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.
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.
The New Relic Lambda Extension (bundled in the layer) reads the telemetry file and forwards the data to New Relic after each invocation.

Lambda 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

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.

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.

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

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.

중요

By default, the Lambda extension or CloudWatch captures your logs. The agent doesn't forward logs directly.

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.

중요

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

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

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.