Configure ATP for host

Preview

We're still working on this feature, but we'd love for you to try it out!

This feature is currently provided as part of a preview pursuant to our pre-release policies.

Learn how to install and configure the Adaptive Telemetry Processor (ATP) with the NRDOT Collector. ATP is included with the standard NRDOT distribution to reduce telemetry data volume while maintaining critical visibility.

Installation options

Choose the installation approach that matches your current setup:

Before you begin

Ensure you have:

Your New Relic license key
Root or sudo privileges.
Network access to GitHub releases

Install NRDOT collector host

ATP comes pre-packaged with the NRDOT collector distribution. Based on your OS, choose your installation method:

Set the environment variables:
bash
```
$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>" #Fetch the latest version from GitHub releases available at https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_arch="amd64"  # Use 'arm64' for ARM processors
$export license_key="<YOUR_NEW_RELIC_LICENSE_KEY>"
```

Download the NRDOT package:

bash

$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.deb" \
>  --location \
>  --output collector.deb

Install the downloaded package:
bash
```
$sudo dpkg -i collector.deb
```

Configure the NRDOT collector to use defined environment variables:

bash

$echo "NEW_RELIC_LICENSE_KEY=${license_key}" | sudo tee -a /etc/${collector_distro}/${collector_distro}.conf > /dev/null

Start the NRDOT collector service:

bash

$sudo systemctl reload-or-restart "${collector_distro}.service"

Set the environment variables:

bash

$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>" #Fetch the latest version from GitHub releases available at https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_arch="x86_64"  # Use 'arm64' for ARM processors
$export license_key="<YOUR_NEW_RELIC_LICENSE_KEY>"

Download the NRDOT package:

bash

$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.rpm" \
>  --location \
>  --output collector.rpm

Install the downloaded package:
bash
```
$sudo rpm -i collector.rpm
```

Configure the NRDOT collector to use defined environment variables:

bash

$echo "NEW_RELIC_LICENSE_KEY=${license_key}" | sudo tee -a /etc/${collector_distro}/${collector_distro}.conf > /dev/null

Start the NRDOT collector service:

bash

$sudo systemctl reload-or-restart "${collector_distro}.service"

Set the environment variables:

bash

$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>" #Fetch the latest version from GitHub releases available at https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_arch="amd64"  # Use 'arm64' for ARM processors
$export license_key="<YOUR_NEW_RELIC_LICENSE_KEY>"

Download the NRDOT collector:

bash

$# Download the tarball
$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.tar.gz" \
>  --location \
>  --output collector.tar.gz

Extract the NRDOT collector:

bash

$# Extract contents
$tar -xzf collector.tar.gz

Run the collector:

bash

$# Run collector in foreground
$NEW_RELIC_LICENSE_KEY="${license_key}" ./nrdot-collector --config ./config.yaml

Configure ATP

Once the NRDOT collector is installed, edit the collector's configuration file to enable and customize ATP. The configuration file paths vary depending on your installation method:

For DEB/RPM installations, the config file is located at /etc/nrdot-collector/config.yaml.
For manual binary installations, the config file is located inside the extracted folder.

To edit the configuration file:

Open the configuration file (config.yaml) with a text editor:
- For DEB/RPM installations:
  bash
```
$sudo nano /etc/nrdot-collector/config.yaml
```
- For manual binary installations:
  bash
```
$nano config.yaml
```
To collect the process metrics, in the scrapers section of hostmetrics receiver, add the following process configuration:
```
receivers:
  hostmetrics:
    scrapers:
      # Your existing scrapers...
      process:
        metrics:
          process.cpu.utilization:
            enabled: true
          process.memory.utilization:
            enabled: true
        mute_process_name_error: true
        mute_process_exe_error: true
        mute_process_io_error: true
        mute_process_user_error: true
```

To enable ATP, locate the existing processors section, and add the adaptivetelemetry configuration underneath it:

processors:
  adaptivetelemetry:
    enable_storage: true
    retention_minutes: 30
    include_process_list:
      - "/usr/bin/postgres"
      - "/usr/sbin/nginx" # Replace with your target processes
    metric_thresholds:
      process.cpu.utilization: 0.05     # 5% CPU
      process.memory.utilization: 0.05  # 5% memory

Add the ATP processor to your metrics pipeline under the service section:

service:
  pipelines:
    metrics/host:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - adaptivetelemetry  # ADD THIS LINE
        - metricstransform
        - filter/exclude_cpu_utilization
        - filter/exclude_memory_utilization

(Optional) Update the ATP configuration such as metric thresholds as required. For more details on configuration options, see the Configuration parameters.
Save the configuration file.
Restart the NRDOT collector to apply changes:
bash
```
$sudo systemctl restart nrdot-collector
```

Access the ATP data in New Relic

Once the ATP is configured, it starts collecting data from your Linux host. You can access this data in New Relic OpenTelemetry UI. For more information on New Relic OpenTelemetry UI, refer to OpenTelemetry APM UI.

To view the ATP process metric data in New Relic:

Go to one.newrelic.com > All Entities.
OR
Go to one.newrelic.com > Catalogs > Infrastructure.
Search for entity where you installed the NRDOT collector with ATP.
Select the entity then click Process in the left pane.
On the Process page, you can view all the processes running on your host, along with their IDs, CPU and memory utilization metrics. It also displays the parent-child relationship between processes if a process spawns other processes.

Before you begin

Ensure you have:

Existing NRDOT Collector version 1.11.0 or later
Your New Relic license key
Root or sudo privileges
Backup of current configuration

Backup current configuration

Safeguard your current settings before proceeding:

bash

$sudo cp /etc/nrdot-collector/config.yaml /etc/nrdot-collector/config.yaml.bak

Upgrade NRDOT collector

To upd the NRDOT collector to the latest version with ATP support, rerun the installation commands for the latest version. This will overwrite the old binary while preserving your existing configuration file.

Set the environment variables:

bash

$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>" #Fetch the latest version from GitHub releases available at https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_arch="amd64"  # Use 'arm64' for ARM processors

Download the latest version of NRDOT collector:

bash

$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.deb" \
>  --location \
>  --output collector.deb

Install the downloaded NRDOT collector package:
bash
```
$sudo dpkg -i collector.deb
```

Set the environment variables:

bash

$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>"
$export collector_arch="x86_64"  # Use 'arm64' for ARM processors

Download the latest version of NRDOT collector:

bash

$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.rpm" \
>  --location \
>  --output collector.rpm

Install the downloaded NRDOT collector package:
bash
```
$sudo rpm -U collector.rpm
```

Stop the running collector and backup your configuration:
bash
```
$pkill -f nrdot-collector
$cp config.yaml config.yaml.bak
```
Follow the installation steps in the New Installation tab → For manual binary section to complete the remaining steps.
Prudence
This will overwrite your current config.yaml, which is why the backup in Step 1 was necessary.

Configure ATP

The upgrade preserved your previous settings, so your config.yaml doesn't yet contain the new ATP settings. You must add them manually.

To edit the configuration file:

Open the configuration file (config.yaml) with a text editor using root or sudo privileges:
- For DEB/RPM installations:
  bash
```
$sudo nano /etc/nrdot-collector/config.yaml
```
- For manual binary installations:
  bash
```
$nano config.yaml
```

To collect the process metrics, in the scrapers section of hostmetrics receiver, add the following process configuration:

processes:
process:
  metrics:
    process.cpu.utilization:
      enabled: true
    process.memory.utilization:
      enabled: true
  mute_process_name_error: true
  mute_process_exe_error: true
  mute_process_io_error: true
  mute_process_user_error: true

To enable ATP, locate the existing processors section, and add the adaptivetelemetry configuration underneath it:

processors:
  # Your existing processors...
  adaptivetelemetry:
    enable_storage: true
    retention_minutes: 30
    include_process_list:
      - "/usr/bin/postgres"
      - "/usr/sbin/nginx" # Replace with your target processes
    metric_thresholds:
      process.cpu.utilization: 0.05     # 5% CPU
      process.memory.utilization: 0.05  # 5% memory

Add the ATP processor to your metrics pipeline under the service section:

service:
  pipelines:
    metrics/host:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - adaptivetelemetry  # ADD THIS LINE
        - metricstransform
        - filter/exclude_cpu_utilization
        - filter/exclude_memory_utilization

(Optional) Update the ATP configuration such as metric thresholds as required. For more details on configuration options, see the Configuration parameters.
Save the configuration file.
Restart the NRDOT collector to apply changes:
bash
```
$sudo systemctl restart nrdot-collector
```

Access the ATP data in New Relic

To view the ATP process metric data in New Relic:

Go to one.newrelic.com > All Entities.
OR
Go to one.newrelic.com > Catalogs > Infrastructure.
Search for entity where you installed the NRDOT collector with ATP.
Select the entity then click Process in the left pane.
On the Process page, you can view all the processes running on your host, along with their IDs, CPU and memory utilization metrics. It also displays the parent-child relationship between processes if a process spawns other processes.

To install ATP by migrating from the New Relic native infrastructure agent to the NRDOT collector host distribution, you need to uninstall the native agent and set up NRDOT with ATP.

Before you begin

Ensure you have:

Your New Relic license key
Root or sudo privileges
Plan for minimal service interruption

Stop and disable native agent

To stop the existing infrastructure agent to prevent data conflict, run:
bash
```
$# Stop the service
$sudo systemctl stop newrelic-infra
```
To disable the infrastructure agent from starting on boot, run:
bash
```
$# Disable from starting on boot
$sudo systemctl disable newrelic-infra
```

Install NRDOT collector host

ATP comes pre-packaged with the NRDOT collector distribution. Based on your OS, choose your installation method:

Set the environment variables:

bash

$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>" #Fetch the latest version from GitHub releases available at https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_arch="amd64"  # Use 'arm64' for ARM processors
$export license_key="<YOUR_NEW_RELIC_LICENSE_KEY>"

Download the NRDOT package:

bash

$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.deb" \
>  --location \
>  --output collector.deb

Install the downloaded package:
bash
```
$sudo dpkg -i collector.deb
```

Configure the NRDOT collector to use defined environment variables:

bash

$echo "NEW_RELIC_LICENSE_KEY=${license_key}" | sudo tee -a /etc/${collector_distro}/${collector_distro}.conf > /dev/null

Start the NRDOT collector service:

bash

$sudo systemctl reload-or-restart "${collector_distro}.service"

Set the environment variables:

bash

$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>" #Fetch the latest version from GitHub releases available at https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_arch="x86_64"  # Use 'arm64' for ARM processors
$export license_key="<YOUR_NEW_RELIC_LICENSE_KEY>"

Download the NRDOT package:

bash

$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.rpm" \
>  --location \
>  --output collector.rpm

Install the downloaded package:
bash
```
$sudo rpm -i collector.rpm
```

Configure the NRDOT collector to use defined environment variables:

bash

$echo "NEW_RELIC_LICENSE_KEY=${license_key}" | sudo tee -a /etc/${collector_distro}/${collector_distro}.conf > /dev/null

Start the NRDOT collector service:

bash

$sudo systemctl reload-or-restart "${collector_distro}.service"

Set the environment variables:

bash

$export collector_distro="nrdot-collector"
$export collector_version="<NRDOT_COLLECTOR_LATEST_VERSION>" #Fetch the latest version from GitHub releases available at https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_arch="amd64"  # Use 'arm64' for ARM processors
$export license_key="<YOUR_NEW_RELIC_LICENSE_KEY>"

Download the NRDOT collector:

bash

$# Download the tarball
$curl "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/${collector_distro}_${collector_version}_linux_${collector_arch}.tar.gz" \
>  --location \
>  --output collector.tar.gz

Extract the NRDOT collector:

bash

$# Extract contents
$tar -xzf collector.tar.gz

Run the collector:

bash

$# Run collector in foreground
$NEW_RELIC_LICENSE_KEY="${license_key}" ./nrdot-collector --config ./config.yaml

Configure ATP

Once the NRDOT collector is installed, edit the collector's configuration file to enable and customize ATP. The configuration file paths vary depending on your installation method:

For DEB/RPM installations, the config file is located at /etc/nrdot-collector/config.yaml.
For manual binary installations, the config file is located inside the extracted folder.

To edit the configuration file:

Open the configuration file (config.yaml) with a text editor:
- For DEB/RPM installations:
  bash
```
$sudo nano /etc/nrdot-collector/config.yaml
```
- For manual binary installations:
  bash
```
$nano config.yaml
```

To collect the process metrics, in the scrapers section of hostmetrics receiver, add the following process configuration:

receivers:
  hostmetrics:
    scrapers:
      # Your existing scrapers...
      process:
        metrics:
          process.cpu.utilization:
            enabled: true
          process.memory.utilization:
            enabled: true
        mute_process_name_error: true
        mute_process_exe_error: true
        mute_process_io_error: true
        mute_process_user_error: true

To enable ATP, locate the existing processors section, and add the adaptivetelemetry configuration underneath it:

processors:
  adaptivetelemetry:
    enable_storage: true
    retention_minutes: 30
    include_process_list:
      - "/usr/bin/postgres"
      - "/usr/sbin/nginx" # Replace with your target processes
    metric_thresholds:
      process.cpu.utilization: 0.05     # 5% CPU
      process.memory.utilization: 0.05  # 5% memory

Add the ATP processor to your metrics pipeline under the service section:

service:
  pipelines:
    metrics/host:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - adaptivetelemetry  # ADD THIS LINE
        - metricstransform
        - filter/exclude_cpu_utilization
        - filter/exclude_memory_utilization

(Optional) Update the ATP configuration such as metric thresholds as required. For more details on configuration options, see the Configuration parameters.
Save the configuration file.
Restart the NRDOT collector to apply changes:
bash
```
$sudo systemctl restart nrdot-collector
```

Verify migration

Once the installation is successful, check that data is flowing to New Relic:

To verify service status, run:
bash
```
$sudo systemctl status nrdot-collector
```
To check logs, run:
bash
```
$sudo journalctl -u nrdot-collector -f
```

Access the ATP data in New Relic

To view the ATP process metric data in New Relic:

Go to one.newrelic.com > All Entities.
OR
Go to one.newrelic.com > Catalogs > Infrastructure.
Search for entity where you installed the NRDOT collector with ATP.
Select the entity then click Process in the left pane.
On the Process page, you can view all the processes running on your host, along with their IDs, CPU and memory utilization metrics. It also displays the parent-child relationship between processes if a process spawns other processes.

Configuration parameters

Parameter	Type	Default	Description
`enable_storage`	boolean	`true`	Enable persistent storage. Storage paths are automatically determined: Linux: `/var/lib/nrdot-collector/adaptiveprocess.db`, Windows: `%LOCALAPPDATA%\nrdot-collector\adaptiveprocess.db`
`retention_minutes`	integer	`30`	How long to retain process state in minutes
`include_process_list`	array	`[]`	Process names to always include (bypasses filtering)
`metric_thresholds`	map	`{}`	Static thresholds per metric type

Parameter	Type	Default	Description
`enable_dynamic_thresholds`	boolean	`false`	Enable adaptive threshold adjustment
`dynamic_smoothing_factor`	float	`0.1`	Smoothing factor for threshold adaptation (0.0-1.0)
`min_thresholds`	map	`{}`	Minimum threshold values per metric
`max_thresholds`	map	`{}`	Maximum threshold values per metric

Parameter	Type	Default	Description
`enable_multi_metric`	boolean	`false`	Enable composite scoring across metrics
`composite_threshold`	float	`1.5`	Threshold for composite score evaluation. This score must be more than `0.0`
`weights`	map	`{}`	Weight values per metric for composite scoring

Parameter	Type	Default	Description
`enable_anomaly_detection`	boolean	`false`	Enable anomaly detection layer
`anomaly_history_size`	integer	`15`	Number of historical data points to track
`anomaly_change_threshold`	float	`50.0`	Percentage change threshold for anomalies
`anomaly_min_data_points`	integer	`3`	Minimum data points required before anomaly detection

Troubleshooting

Learn how to troubleshoot ATP issues for your environment.

Query your data

Learn how to query ATP data in New Relic using NRQL.

Advanced-features

Learn how to enable advanced features for your ATP deployment.

Preview

Installation options

Before you begin

Install NRDOT collector host

For Debian/Ubuntu

For RHEL/CentOS

For manual binary

Configure ATP

Access the ATP data in New Relic

Before you begin

Backup current configuration

Upgrade NRDOT collector

For Debian/Ubuntu

For RHEL/CentOS

For manual binary

Prudence

Configure ATP

Access the ATP data in New Relic

Before you begin

Stop and disable native agent

Install NRDOT collector host

For Debian/Ubuntu

For RHEL/CentOS

For manual binary

Configure ATP

Verify migration

Access the ATP data in New Relic

Configuration parameters

Core settings

Dynamic thresholds

Multi-metric composite scoring

Anomaly detection

Troubleshooting

Query your data

Advanced-features

Configure ATP for host

Preview

Installation options .css-21sua1{background:none;border:none;width:0;padding:0;}

Before you begin

Install NRDOT collector host

For RHEL/CentOS

For manual binary

Configure ATP

Access the ATP data in New Relic

Before you begin

Backup current configuration

Upgrade NRDOT collector

For Debian/Ubuntu

For RHEL/CentOS

For manual binary

Configure ATP

Access the ATP data in New Relic

Before you begin

Stop and disable native agent

Install NRDOT collector host

For Debian/Ubuntu

For RHEL/CentOS

For manual binary

Configure ATP

Verify migration

Access the ATP data in New Relic

Configuration parameters

Core settings

Dynamic thresholds

Multi-metric composite scoring

Anomaly detection

Related resources

Troubleshooting

Query your data

Advanced-features

Installation options