• /
  • EnglishEspañolFrançais日本語한국어Português
  • Log inStart now

Modify agent configuration

|View as Markdown

For the gateway to process your agents' telemetry data, reconfigure them to route data to your gateway cluster instead of directly to New Relic. How you do that depends on the agent type: New Relic APM agents use NEW_RELIC_HOST, OpenTelemetry sources use OTLP exporter settings, and log forwarders use their own output plugin configuration. The sections below cover each agent type. All examples use the cluster-local gateway endpoint. Replace it with your actual endpoint if agents run outside the cluster.

New Relic APM agents

NEW_RELIC_HOST is APM-only and has no effect on OpenTelemetry sources, the Infrastructure agent, or log forwarders. The gateway endpoint must be reachable over HTTPS, so APM agents connect through the in-cluster reverse proxy (NGINX or Kong) or the out-of-cluster ALB, not directly to the gateway pod.

The following example shows a Node.js agent configuration file:

'use strict'
/**
* New Relic agent configuration.
*
* See lib/config/default.js in the agent distribution for a more complete
* description of configuration variables and their potential values.
*/
exports.config = {
/**
* Array of application names.
*/
app_name: ['My Application'],
/**
* Your New Relic Host endpoint.
*/
NEW_RELIC_HOST: 'GATEWAY_DNS_ENDPOINT_HERE',
/**
* Your New Relic license key.
*/
license_key: 'license key here',
logging: {
/**
* Level at which to log. 'trace' is most useful to New Relic when diagnosing
* issues with the agent, 'info' and higher will impose the least overhead on
* production applications.
*/
level: 'info'
},
/**
* When true, all request headers except for those listed in attributes.exclude
* will be captured for all traces, unless otherwise specified in a destination's
* attributes include/exclude lists.
*/
allow_all_headers: true,
attributes: {
/**
* Prefix of attributes to exclude from all destinations. Allows * as wildcard
* at end.
*
* NOTE: If excluding headers, they must be in camelCase form to be filtered.
*
* @name NEW_RELIC_ATTRIBUTES_EXCLUDE
*/
exclude: [
'request.headers.cookie',
'request.headers.authorization',
'request.headers.proxyAuthorization',
'request.headers.setCookie*',
'request.headers.x*',
'response.headers.cookie',
'response.headers.authorization',
'response.headers.proxyAuthorization',
'response.headers.setCookie*',
'response.headers.x*'
]
}
}

OpenTelemetry Collector

Minimum version: opentelemetry-collector-contrib v0.104.0

Use the otlphttp exporter pointed at the gateway's OTLP HTTP port. Deploy this configuration as a Kubernetes ConfigMap:

exporters:
otlphttp:
endpoint: http://pipeline-control-gateway.newrelic.svc.cluster.local:4318
tls:
insecure: true
service:
pipelines:
traces:
exporters: [otlphttp]
metrics:
exporters: [otlphttp]
logs:
exporters: [otlphttp]

Important

Use the otlphttp exporter, not otlp. The Helm chart renames otlp to otlp_grpc internally, which is invalid for this collector version.

eBPF auto-attach agent

Configure the eBPF APM auto-attach agent to send telemetry via OTLP gRPC by setting customOtlpEndpoint in your values file:

customOtlpEndpoint: "pipeline-control-gateway.newrelic.svc.cluster.local:4317"
customOtlpEndpointTlsEnabled: false
reportLogs: "true"

This routes both metrics and logs through the gateway's OTLP gRPC receiver on port 4317. TLS is disabled because the connection stays within the cluster.

Infrastructure agent

Minimum version: v1.62.0

Three configuration keys control which telemetry the Infrastructure agent routes through the gateway:

  • collector_url — routes infrastructure samples (such as SystemSample and ProcessSample) and inventory. The gateway processes samples. Inventory is passed through to New Relic unchanged (base URL, no trailing path).
  • metric_url — routes dimensional metrics (base URL, no trailing path).
  • logging_endpoint — routes logs (full URL including /log/v1).

To route all of the agent's telemetry through the gateway, set collector_url, metric_url, and logging_endpoint (on Kubernetes, set newrelic-logging.endpoint instead of logging_endpoint). collector_url and metric_url alone do not route logs.

Important

Agent registration (identity-api.newrelic.com) and the command channel (infrastructure-command-api.newrelic.com) always connect directly to New Relic — they bypass the gateway regardless of these settings. Hosts still need egress to both endpoints.

Route infrastructure samples, metrics, and inventory through the gateway

Kubernetes (nri-bundle Helm values):

newrelic-infrastructure:
common:
agentConfig:
collector_url: "http://pipeline-control-gateway.newrelic.svc.cluster.local"
metric_url: "http://pipeline-control-gateway.newrelic.svc.cluster.local"

Host (/etc/newrelic-infra.yml):

license_key: YOUR_LICENSE_KEY
collector_url: http://GATEWAY_ADDRESS
metric_url: http://GATEWAY_ADDRESS

Replace GATEWAY_ADDRESS with pipeline-control-gateway.newrelic.svc.cluster.local for agents running inside the cluster, or the gateway's load balancer address for agents on external hosts.

Route logs through the gateway

In Kubernetes nri-bundle deployments, log forwarding is handled by the newrelic-logging chart, not the Infrastructure agent. Set the logging endpoint in your Helm values:

newrelic-logging:
endpoint: "http://pipeline-control-gateway.newrelic.svc.cluster.local/log/v1"

For host-based installs, set logging_endpoint in /etc/newrelic-infra.yml:

license_key: YOUR_LICENSE_KEY
logging_endpoint: http://pipeline-control-gateway.newrelic.svc.cluster.local/log/v1

Use http:// for the cluster-local endpoint. Use https:// only when routing through an in-cluster reverse proxy (NGINX or Kong) with cert-manager deployed.

Then define which log files to forward in /etc/newrelic-infra/logging.d/logging.yml:

logs:
- name: my-app-logs
file: /var/log/my-app.log

Restart the Infrastructure agent to apply the changes.

Compatibility matrix: Supported agents and versions

The following table lists the New Relic APM agents, Infrastructure agents, and log collectors supported for use with the gateway. Note that support for the Gateway feature doesn't override the general New Relic end-of-life (EOL) policies or any applicable agent-specific EOL policies..

Agent type/Language

Versions available

New Relic APM agents

See language-specific versions below:

    .NET

8.17.438 and later

    Go

2.2.0 and later

    Java

4.9.0 and later

    NodeJS

6.10.0 and later

    PHP

10.0.0 and later

    Python

4.10.0 and later

    Ruby

6.1.0 and later

Infrastructure agent

1.62.0 and later

Kubernetes agent

v3.33.2 and later

Fluent Bit agent

2.3.0 and later

OpenTelemetry Collector

opentelemetry-collector-contrib v0.104.0 and later

MELT APIs

NA

The versions listed are representative of the range available for each language. For detailed version information, refer to the specific agent documentation.

Next topic

Copyright © 2026 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.