Serverless and Cloud
This page covers running the agent in AWS Lambda (serverless mode), Azure, Google Cloud Run, Heroku, and under New Relic Agent Control, plus the cloud and container detection the agent performs at startup.
AWS Lambda: Serverless Mode
In serverless mode the agent does not connect to the collector from the function. Instead, it serializes the data at the end of each invocation and hands it off — to the New Relic Lambda extension through a named pipe when it exists, or to stdout (CloudWatch Logs) otherwise.
Enabling it
serverless_mode.enabled is turned on automatically when the AWS_LAMBDA_FUNCTION_NAME environment variable is present, unless you set serverless_mode.enabled explicitly in the file or with NEW_RELIC_SERVERLESS_MODE_ENABLED. Explicit values always win.
Wrapping the handler
'use strict'
const newrelic = require('newrelic')
module.exports.handler = newrelic.setLambdaHandler(async (event, context) => {
// your code
return { statusCode: 200, body: JSON.stringify({ ok: true }) }
})
See setLambdaHandler. The event source (API Gateway, SQS, SNS, S3, and others defined in lib/serverless/event-sources.json) is detected from the shape of the event.
What serverless mode changes
| Aspect | Behavior in serverless mode |
|---|---|
| License key | Not required (the license_key startup blocker is skipped). |
app_name |
If unset, defaults to the value of AWS_LAMBDA_FUNCTION_NAME (or Serverless Application), logged as Auto-naming serverless application to [...]. |
| Agent log | logging.enabled is set to false unless you set it in the file or with NEW_RELIC_LOG_ENABLED. If you enable it, point logging.filepath at stdout, stderr, or a writable path such as /tmp. |
| VM metrics | virtual_machine.collect_metrics.enabled is set to false unless you enable it (or the deprecated plugins.native_metrics.enabled) explicitly; enabling it logs a note that it adds overhead to every event loop iteration. |
| Infinite Tracing | Forced off. |
| Distributed tracing | Requires account_id. Without it, distributed tracing is disabled with a warning. With it, trusted_account_key defaults to account_id and primary_application_id to Unknown. |
account_id, trusted_account_key, primary_application_id |
Only honored locally in serverless mode; elsewhere they come from the server. |
Data hand-off
| Setting / variable | Default | Effect |
|---|---|---|
NEWRELIC_PIPE_PATH (environment) |
/tmp/newrelic-telemetry |
Named pipe of the Lambda extension. If the path exists, the payload is written there. |
| — | — | If the pipe does not exist, or writing fails (Error attempting to write to pipe, falling back to stdout), the payload is written to stdout. |
NEWRELIC_PIPE_PATH uses the NEWRELIC_ prefix (no underscore after NEW) and is read directly by the serverless collector; it is not a configuration setting.
Unified APM UI
apm_lambda_mode: true (NEW_RELIC_APM_LAMBDA_MODE) makes the Lambda instrumentation add the data needed by the unified APM experience (introduced in 2025).
A typical Lambda configuration
NEW_RELIC_NO_CONFIG_FILE=true
NEW_RELIC_ACCOUNT_ID=1234567
NEW_RELIC_TRUSTED_ACCOUNT_KEY=1234567
NEW_RELIC_LOG_ENABLED=true
NEW_RELIC_LOG=stdout
NEW_RELIC_LOG_LEVEL=info
Azure
| Feature | Details |
|---|---|
| App Service naming | If app_name is not set anywhere, the APP_POOL_ID environment variable is used (split on commas). |
| Azure Functions | @azure/functions (4.7.0+) is instrumented. utilization.detect_azurefunction reads environment variables and invocation context to describe the function. |
| VM metadata | utilization.detect_azure queries Azure's metadata service. |
| Site extension | The repository includes an Azure App Service site extension under cloud-tooling/azure-site-extension. |
Google Cloud Run
On Cloud Run (detected through K_SERVICE and related variables), the agent can use the GCP metadata instance ID as the host name:
| Setting | Default | Effect |
|---|---|---|
utilization.gcp_cloud_run.use_instance_as_host |
true |
Use the GCP instance ID as the host name for Services, Worker Pools, and Jobs. |
utilization.gcp_cloud_run.include_revision_in_host |
false |
Prepend the revision (K_REVISION for services, CLOUD_RUN_REVISION for worker pools, CLOUD_RUN_EXECUTION for jobs), producing {revision}-{instance id}. |
utilization.gcp_use_instance_as_host |
true |
Deprecated, to be removed in v15. Replaced by utilization.gcp_cloud_run.use_instance_as_host. |
Heroku
With heroku.use_dyno_names: true (the default) and the DYNO environment variable present, the dyno name (for example web.1) is used as the host name.
Host Naming Elsewhere
| Setting | Effect |
|---|---|
process_host.display_name |
A display name for the host (must be under 255 bytes, otherwise Custom host display name must be less than 255 bytes is logged). |
process_host.ipv_preference |
'4' (default) or '6': which IP family to prefer when building host names. |
utilization.billing_hostname, utilization.logical_processors, utilization.total_ram_mib |
Override detected values reported for utilization. |
Cloud and Container Detection
At startup the agent gathers environment facts. Each probe can be turned off — useful to avoid metadata-service timeouts or network calls in restricted environments:
| Setting | Probes |
|---|---|
utilization.detect_aws |
AWS instance metadata. |
utilization.detect_azure |
Azure instance metadata. |
utilization.detect_azurefunction |
Azure Functions environment. |
utilization.detect_gcp |
GCP metadata. |
utilization.detect_pcf |
Pivotal Cloud Foundry. |
utilization.detect_docker |
Container ID from files. |
utilization.detect_kubernetes |
Kubernetes environment. |
cloud.aws.account_id lets you state the AWS account ID associated with the app.
Agent Control and Health Files
When the agent is managed by New Relic Agent Control, agent_control.enabled: true turns on health reporting. Every agent_control.health.frequency seconds (default 5), the agent writes a health status file into agent_control.health.delivery_location (default file:///newrelic/apm/health).
Health codes come from lib/health-reporter.js:
| Code | Meaning |
|---|---|
NR-APM-000 |
Healthy |
NR-APM-001 |
Invalid license key |
NR-APM-002 |
License key missing |
NR-APM-003 |
Forced disconnect |
NR-APM-004 |
Backend error |
NR-APM-005 |
Missing application name |
NR-APM-006 |
Maximum application names exceeded |
NR-APM-007 |
HTTP proxy misconfigured |
NR-APM-008 |
Agent disabled |
NR-APM-009 |
Connection error |
NR-APM-010 |
Configuration parse failure |
NR-APM-099 |
Agent shutdown |
NR-APM-300 |
Unexpected internal error |