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: falsereportLogs: "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 asSystemSampleandProcessSample) 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_KEYcollector_url: http://GATEWAY_ADDRESSmetric_url: http://GATEWAY_ADDRESSReplace 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_KEYlogging_endpoint: http://pipeline-control-gateway.newrelic.svc.cluster.local/log/v1Use 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.logRestart 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: |
8.17.438 and later | |
2.2.0 and later | |
4.9.0 and later | |
6.10.0 and later | |
10.0.0 and later | |
4.10.0 and later | |
6.1.0 and later | |
1.62.0 and later | |
v3.33.2 and later | |
2.3.0 and later | |
opentelemetry-collector-contrib v0.104.0 and later | |
NA |
The versions listed are representative of the range available for each language. For detailed version information, refer to the specific agent documentation.