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.
Importante
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-telemetryand 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-coremodules. This means Java Lambda handlers that implementRequestHandlerorRequestStreamHandlerare 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 |
|
Slim (recommended) | ARM64 |
|
Full | x86_64 |
|
Full | ARM64 |
|
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:
RequestHandlerimplementation:com.newrelic.java.HandlerWrapper::handleRequestRequestStreamHandlerimplementation: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 |
|---|---|---|
|
| Enables serverless mode. Set to |
|
| By default, this sets the Java agent log file path to |
|
| 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. |
|
| Disables in-agent log forwarding. Set by the layer if not already defined. Logs are captured via CloudWatch or the Lambda extension instead. |
|
| Always set to |
The following environment variables are required and must be set by you:
Environment variable | Required value | Description |
|---|---|---|
|
| Points AWS Lambda to the New Relic Java agent wrapper. This must always be set to |
| Your New Relic license key | Your New Relic ingest license key, used to authenticate telemetry sent to New Relic. |
| 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. |
Importante
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.
Importante
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.