• /
  • EnglishEspañolFrançais日本語한국어Português
  • EntrarComeçar agora

Agent Control settings reference

|View as Markdown (English)

This page lists the Agent Control settings you can modify, with their default values. For an overview of local and remote configuration, and for examples of how to configure the agents that Agent Control manages, see Managing configurations.

The Fleet Control connection (fleet_control), host_id, the managed agents, and value providers are covered in Managing configurations.

How Agent Control reads its settings

Agent Control reads its settings from the local configuration file:

Environment

Local configuration file

Linux

/etc/newrelic-agent-control/local-data/agent-control/local_config.yaml

Windows

C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml

Kubernetes

The agentControlDeployment.chartValues.config section of your values.yaml file

Importante

Only the agents setting and the version settings used for upgrades can be changed through remote configuration from Fleet Control. All other settings on this page are local: change them in the local configuration file or with environment variables, and restart Agent Control to apply them.

Override settings with environment variables

You can set any setting as an environment variable. Use the NR_AC_ prefix, write the setting name in uppercase, and use a double underscore (__) to separate nested keys. Environment variables take precedence over the local configuration file.

bash
$
# log.level
$
NR_AC_LOG__LEVEL=DEBUG
$
$
# fleet_control.auth_config.client_id
$
NR_AC_FLEET_CONTROL__AUTH_CONFIG__CLIENT_ID="some-client-id"

On hosts, you can define these variables in the service environment file or in an environment_variables.yaml file in the local configuration directory (/etc/newrelic-agent-control/ on Linux, C:\Program Files\New Relic\newrelic-agent-control\ on Windows). The file must be a flat YAML map of string keys to string values:

NR_AC_LOG__LEVEL: "DEBUG"
HTTPS_PROXY: "http://proxy.local:8443"
  • Keys must start with a letter or underscore, and contain only letters, digits, and underscores.
  • Agent Control doesn't watch this file. Restart Agent Control after you change it.
  • Agent Control passes these variables to the agents it manages.
  • If the file has an invalid entry, Agent Control fails to start.

Logging: log

Use the log setting to change the log level, enable file logging, or change the log format.

log:
level: debug
format:
formatter: pretty
target: true
file:
enabled: true
path: /var/log/my-folder/agent-control.log

Setting

Description

Default

log.level

Log level: error, warn, info, debug, or trace. Only Agent Control's own components log at this level; logs from external dependencies stay disabled.

info

log.insecure_fine_grained_level

A tracing filter directive (for example, debug) that also enables logs from external dependencies. When you set it, log.level is ignored. This setting is insecure because external dependencies can log sensitive data, such as HTTP headers. Use it only for short debugging sessions.

(empty)

log.format.formatter

json for newline-delimited JSON logs, or pretty for human-readable single-line logs.

json

log.format.target

Include the log target (the module that emitted the log) in each log line.

false

log.format.timestamp

Timestamp format, using strftime specifiers.

%Y-%m-%dT%H:%M:%S

log.format.ansi_colors

Use ANSI colors in the logs sent to standard error.

false

log.file.enabled

Write logs to a file.

false

log.file.path

Path of the log file. If you don't set it, Agent Control writes newrelic-agent-control.log in its default log directory.

(default log directory)

log.show_spans

Show tracing spans as log lines. Spans add details that can help with debugging.

false

Dica

Log files rotate daily, and Agent Control keeps the last 30 files. You can't change this behavior.

Proxy: proxy

Agent Control uses the HTTP_PROXY and HTTPS_PROXY environment variables of your system. You can also set a proxy with the proxy setting. If more than one is defined, Agent Control uses them in this order of precedence:

  1. The proxy setting
  2. The HTTP_PROXY environment variable
  3. The HTTPS_PROXY environment variable
proxy:
url: https://user:password@proxy.example.com:8080
ca_bundle_file: /etc/ssl/certs/proxy-ca.pem

Setting

Description

Default

proxy.url

Proxy URL, in the format <protocol>://<user>:<password>@<host>:<port>.

(empty)

proxy.ca_bundle_dir

Directory with CA certificates in PEM format. Agent Control reads all .pem files in it.

(empty)

proxy.ca_bundle_file

Path to a CA certificate bundle in PEM format.

(empty)

proxy.ignore_system_proxy

Ignore the HTTP_PROXY and HTTPS_PROXY environment variables.

false

Cuidado

The proxy you configure in Agent Control isn't applied automatically to the agents it manages. Configure the proxy separately for each agent.

Status server: server

The local status server reports the status of Agent Control and its managed agents. For how to query it, see Monitoring with Agent Control.

server:
enabled: true
host: "127.0.0.1"
port: 51200

Setting

Description

Default

server.enabled

Enable the status server.

false

server.host

Address the status server listens on.

127.0.0.1

server.port

Port the status server listens on.

51200

Health checks: health_check

health_check:
interval: 60s
initial_delay: 60s

Setting

Description

Default

health_check.interval

Time between Agent Control health checks.

30s

health_check.initial_delay

Time to wait before the first health check.

30s

Uptime report: uptime_report

Agent Control reports its uptime as a metric when self-instrumentation metrics are enabled.

uptime_report:
enabled: true
interval: 60s

Setting

Description

Default

uptime_report.enabled

Report the uptime of Agent Control.

true

uptime_report.interval

Time between uptime reports.

60s

Self-instrumentation: self_instrumentation

Agent Control can report its own logs and metrics using OpenTelemetry. If you configure a proxy, self-instrumentation uses it.

self_instrumentation:
opentelemetry:
endpoint: https://otlp.nr-data.net:4318
headers:
api-key: YOUR_LICENSE_KEY
metrics:
enabled: true
interval: 120s
logs:
enabled: true

Setting

Description

Default

self_instrumentation.opentelemetry.endpoint

HTTPS endpoint that receives the OTLP data. Required when opentelemetry is set. For New Relic, use the api-key header to authenticate.

(none)

self_instrumentation.opentelemetry.headers

Headers added to every request to the endpoint.

(empty)

self_instrumentation.opentelemetry.client_timeout

Timeout for requests to the endpoint.

30s

self_instrumentation.opentelemetry.custom_attributes

Attributes added to all reported metrics and logs.

(empty)

self_instrumentation.opentelemetry.insecure_level

Filter directive that defines which logs are reported. It's insecure because enabling external dependencies can leak sensitive data. The default only includes Agent Control components.

newrelic_agent_control=debug,opamp_client=debug,off

self_instrumentation.opentelemetry.metrics.enabled

Report metrics.

false

self_instrumentation.opentelemetry.metrics.interval

Time between metric reports.

60s

self_instrumentation.opentelemetry.logs.enabled

Report logs.

false

self_instrumentation.opentelemetry.logs.batch_config.scheduled_delay

Delay between batch exports of logs.

30s

self_instrumentation.opentelemetry.logs.batch_config.max_size

Maximum number of logs in a single batch.

512

OCI registry: oci

Agent Control pulls agent packages from an OCI registry.

oci:
registry: "docker.io"
auth:
basic:
username: "my-user"
password: "my-password"

Setting

Description

Default

oci.registry

Registry host name or URL. It can't be empty.

docker.io

oci.auth.basic.username, oci.auth.basic.password

Credentials for basic authentication.

Anonymous access

oci.auth.bearer.token

Token for bearer authentication.

Anonymous access

If you set oci.auth, define exactly one of basic or bearer.

Package and agent type verification

Agent Control verifies the signatures of the packages it downloads and of the agent type definitions it pulls. Only disable verification for testing: Agent Control logs a warning when it's disabled.

agent_packages:
signature_verification_enabled: true
agent_types:
default_remote:
signature_verification_enabled: true

Setting

Description

Default

agent_packages.signature_verification_enabled

Verify the signature of agent packages.

true

agent_types.default_remote.signature_verification_enabled

Verify the signature of agent type definitions.

true

agent_types.default_remote.repository

Repository, in the configured oci.registry, that holds the agent type definitions.

New Relic's agent types repository

agent_types.default_remote.public_key_url

JWKS URL of the public key used to verify agent type signatures.

New Relic's public key URL

Self-update on hosts: self_update

On hosts, Agent Control can update itself when Fleet Control deploys a new version.

self_update:
download_retry:
max_attempts: 3
upgrade_backoff:
base_delay: 30s
max_delay: 600s

Setting

Description

Default

self_update.signature_verification_enabled

Verify the signature of the Agent Control package.

true

self_update.package.download.oci.repository

OCI repository that holds the Agent Control packages.

New Relic's repository

self_update.package.download.oci.public_key_url

JWKS URL of the public key used to verify the package signature.

New Relic's public key URL

self_update.download_retry.max_attempts

Maximum download attempts per update attempt. Must be greater than zero.

3

self_update.download_retry.base_delay

Initial delay between download retries.

1s

self_update.download_retry.max_delay

Maximum delay between download retries.

30s

self_update.download_retry.jitter

Add random jitter to the retry delays.

true

self_update.upgrade_backoff.max_consecutive_failures

Number of consecutive failed upgrades before Agent Control escalates the failure report. It keeps retrying at max_delay. Must be greater than zero.

5

self_update.upgrade_backoff.base_delay

Initial wait before retrying a failed upgrade.

30s

self_update.upgrade_backoff.max_delay

Maximum wait before retrying a failed upgrade.

600s

self_update.upgrade_backoff.jitter

Add random jitter to the upgrade retry delays.

true

Kubernetes settings: k8s

The Agent Control Helm chart sets most of the k8s settings for you. Change them only if you manage the deployment yourself.

k8s:
cluster_name: "my-cluster"
namespace: "newrelic-agent-control"
namespace_agents: "newrelic-agent-control-agents"

Setting

Description

Default

k8s.cluster_name

Required. Name that identifies the cluster in Fleet Control.

(none)

k8s.namespace

Required. Namespace where Agent Control creates the resources it manages directly.

(none)

k8s.namespace_agents

Required. Namespace where Agent Control creates the resources of the managed agents.

(none)

k8s.current_chart_version

Version of the chart used to deploy Agent Control. The Helm chart passes it as an environment variable to avoid race conditions after a failed upgrade.

(empty)

k8s.ac_remote_update

Apply remote updates of the Agent Control chart. When false, Agent Control ignores them.

false

k8s.ac_release_name

Helm release name of Agent Control. If it's empty, Agent Control doesn't check its own health or apply updates.

(empty)

k8s.cd_enabled

Whether the continuous deployment (Flux) component is enabled. When false, Agent Control doesn't check the health of that component or update it, and it also disables remote updates for it and for Agent Control.

true

k8s.cd_remote_update

Apply remote updates of the Agent Control CD chart. When false, Agent Control ignores them and doesn't check the health of that component.

false

k8s.cd_release_name

Helm release name of the Agent Control CD chart.

(empty)

k8s.auth_secret.secret_name

Name of the Kubernetes secret that holds the credentials.

newrelic-agent-control-secret

k8s.auth_secret.secret_key_name

Key in the secret that holds the credential value.

api-key

Copyright © 2026 New Relic Inc.

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