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

See Also