Instrument your systems with Agent Control

Instrument a clean system

Kubernetes

1. Create a fleet of type Kubernetes Cluster in Fleet Control. See Create your first fleet for detailed steps.

2. Install Agent Control. Follow the Kubernetes installation guide and select the fleet you created in Step 1.

3. Create configurations in Fleet Control for each of your agents. After Agent Control connects to Fleet Control, create configurations for each of your agents. Fleet Control is the authoritative source for all agent configuration, do not add agent-specific values to the local values.yaml.

   Example adding the Infrastructure Agent, Fluent Bit, Prometheus, and NRDOT with custom settings, each of these configurations should be created as a separate remote configuration in Fleet Control:

   Infrastructure agent

   Enables the New Relic Infrastructure agent with custom tolerations and a 30-second collection interval.

   chart_values:
     newrelic-infrastructure:
       kubelet:
         tolerations:
           - operator: "Exists"
             effect: "NoSchedule"
           - operator: "Exists"
             effect: "NoExecute"
       common:
         config:
           interval: 30s

   Copy

   Fluent Bit (log forwarding)

   Deploys the Fluent Bit log forwarder with bounded CPU resources.

   chart_values:
     newrelic-logging:
       resources:
         limits:
           cpu: 200m
         requests:
           cpu: 200m

   Copy

   Prometheus

   Deploys the Prometheus agent in low-data mode to reduce telemetry volume.

   chart_values:
     newrelic-prometheus-agent:
       lowDataMode: true
       config:
         kubernetes:
           integrations_filter:
             enabled: false

   Copy

   NRDOT (OpenTelemetry collector)

   Deploys the New Relic distribution of the OpenTelemetry collector. The filelog receiver is disabled here — enable it if you want log collection.

   chart_values:
     nr-k8s-otel-collector:
       receivers:
         filelog:
           enabled: false

   Copy

4. Create a new deployment adding the just-created remote configurations to your fleet. Agent Control will automatically apply the new configuration to your cluster. Follow these steps in create and run your first deployment.

5. Verify data is flowing. Navigate to Infrastructure > Kubernetes in the New Relic UI. Your cluster should appear within 1–2 minutes of the remote configuration being applied. If it does not appear, see Agent Control troubleshooting.

Linux

1. Create a fleet of type Linux Host in Fleet Control. See Create your first fleet for detailed steps.

2. Install Agent Control. Follow the Linux installation guide and select the fleet you created in Step 1.

3. Create configurations in Fleet Control for each of your agents. After Agent Control connects to Fleet Control, create configurations for each of your agents.

   Example adding the Infrastructure Agent, nri-mysql, nri-flex, fluentbit and nrdot, each of these configurations should be created as a separate remote configuration in Fleet Control:

   Infrastructure agent (baseline)

   config_agent contains the minimum required configuration. license_key is resolved at runtime from the NEW_RELIC_LICENSE_KEY environment variable using the nr-env value provider; custom_attributes is optional but recommended for filtering. config_logging forwards the system syslog to New Relic Logs.

   config_agent:
     license_key: '${nr-env:NEW_RELIC_LICENSE_KEY}'
     custom_attributes:
       env: production
   config_logging:
     logging.yml:
       logs:
         - name: syslog
           file: /var/log/syslog
           attributes:
             logtype: linux_syslog

   Copy

   nri-mysql (on-host integration)

   Monitors a MySQL instance running on localhost. The password is resolved at runtime from the MYSQL_PASSWORD environment variable using the nr-env value provider — never hard-code credentials.

   config:
     integrations:
       - name: nri-mysql
         env:
           HOSTNAME: localhost
           PORT: 3306
           USERNAME: newrelic
           PASSWORD: ${nr-env:MYSQL_PASSWORD}
           REMOTE_MONITORING: true
         interval: 30s

   Copy

   nri-flex with shell command (on-host integration)

   Collects disk usage statistics from the root filesystem using df. This example demonstrates how to run any shell command and parse its output as New Relic events.

   config:
     integrations:
       - name: nri-flex
         config:
           name: diskUsage
           apis:
             - event_type: DiskUsageSample
               commands:
                 - run: df -kP /
                   split: horizontal
                   split_by: \s+
                   set_header: [filesystem, blocks, used, available, usePercent, mountpoint]
                   row_start: 1

   Copy

   NRDOT (OpenTelemetry collector)

   Collects host metrics and system logs, and opens an OTLP receiver for APM services. The license key and OTLP endpoint are injected automatically by Agent Control.

   config:
     # Variables set automatically by Agent Control:
     # - NEW_RELIC_LICENSE_KEY: New Relic ingest license key.
     # - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint (see: https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/).
   
     extensions:
       health_check:
   
     receivers:
       otlp:
         protocols:
           grpc:
           http:
   
       hostmetrics:
         collection_interval: 60s
         scrapers:
           cpu:
             metrics:
               system.cpu.time:
                 enabled: false
               system.cpu.utilization:
                 enabled: true
           load:
           memory:
             metrics:
               system.memory.utilization:
                 enabled: true
           paging:
             metrics:
               system.paging.utilization:
                 enabled: false
               system.paging.faults:
                 enabled: false
           filesystem:
             metrics:
               system.filesystem.utilization:
                 enabled: true
           disk:
             metrics:
               system.disk.merged:
                 enabled: false
               system.disk.pending_operations:
                 enabled: false
               system.disk.weighted_io_time:
                 enabled: false
           network:
             metrics:
               system.network.connections:
                 enabled: false
           # Uncomment to enable process metrics, which can be noisy but valuable.
           # processes:
           # process:
           #  metrics:
           #    process.cpu.utilization:
           #      enabled: true
           #    process.cpu.time:
           #      enabled: false
   
       filelog:
         include:
           - /var/log/alternatives.log
           - /var/log/cloud-init.log
           - /var/log/auth.log
           - /var/log/dpkg.log
           - /var/log/syslog
           - /var/log/messages
           - /var/log/secure
           - /var/log/yum.log
   
     processors:
       metricstransform:
         transforms:
           - include: system.cpu.utilization
             action: update
             operations:
               - action: aggregate_labels
                 label_set: [state]
                 aggregation_type: mean
           - include: system.paging.operations
             action: update
             operations:
               - action: aggregate_labels
                 label_set: [direction]
                 aggregation_type: sum
       filter/exclude_cpu_utilization:
         metrics:
           datapoint:
             - 'metric.name == "system.cpu.utilization" and attributes["state"] == "interrupt"'
             - 'metric.name == "system.cpu.utilization" and attributes["state"] == "nice"'
             - 'metric.name == "system.cpu.utilization" and attributes["state"] == "softirq"'
       filter/exclude_memory_utilization:
         metrics:
           datapoint:
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_unreclaimable"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "inactive"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "cached"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "buffered"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_reclaimable"'
       filter/exclude_memory_usage:
         metrics:
           datapoint:
             - 'metric.name == "system.memory.usage" and attributes["state"] == "slab_unreclaimable"'
             - 'metric.name == "system.memory.usage" and attributes["state"] == "inactive"'
       filter/exclude_filesystem_utilization:
         metrics:
           datapoint:
             - 'metric.name == "system.filesystem.utilization" and attributes["type"] == "squashfs"'
       filter/exclude_filesystem_usage:
         metrics:
           datapoint:
             - 'metric.name == "system.filesystem.usage" and attributes["type"] == "squashfs"'
             - 'metric.name == "system.filesystem.usage" and attributes["state"] == "reserved"'
       filter/exclude_filesystem_inodes_usage:
         metrics:
           datapoint:
             - 'metric.name == "system.filesystem.inodes.usage" and attributes["type"] == "squashfs"'
             - 'metric.name == "system.filesystem.inodes.usage" and attributes["state"] == "reserved"'
       filter/exclude_system_disk:
         metrics:
           datapoint:
             - 'metric.name == "system.disk.operations" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.merged" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.io" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.io_time" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.operation_time" and IsMatch(attributes["device"], "^loop.*") == true'
       filter/exclude_system_paging:
         metrics:
           datapoint:
             - 'metric.name == "system.paging.usage" and attributes["state"] == "cached"'
             - 'metric.name == "system.paging.operations" and attributes["type"] == "cached"'
       filter/exclude_network:
         metrics:
           datapoint:
             - 'IsMatch(metric.name, "^system.network.*") == true and attributes["device"] == "lo"'
       attributes/exclude_system_paging:
         include:
           match_type: strict
           metric_names:
             - system.paging.operations
         actions:
           - key: type
             action: delete
       cumulativetodelta:
       transform/host:
         metric_statements:
           - context: metric
             statements:
               - set(description, "")
               - set(unit, "")
       transform:
         trace_statements:
           - context: span
             statements:
               - truncate_all(attributes, 4095)
               - truncate_all(resource.attributes, 4095)
         log_statements:
           - context: log
             statements:
               - truncate_all(attributes, 4095)
               - truncate_all(resource.attributes, 4095)
       memory_limiter:
         check_interval: 1s
         limit_mib: 100
       batch:
       resourcedetection:
         detectors: ["system"]
         system:
           hostname_sources: ["os"]
           resource_attributes:
             host.id:
               enabled: true
       resourcedetection/cloud:
         detectors: ["gcp", "ec2", "azure"]
         timeout: 2s
         ec2:
           resource_attributes:
             host.name:
               enabled: false
       resourcedetection/env:
         detectors: ["env"]
         timeout: 2s
         override: true
   
     exporters:
       otlphttp:
         endpoint: ${nr-env:OTEL_EXPORTER_OTLP_ENDPOINT}
         headers:
           api-key: ${nr-env:NEW_RELIC_LICENSE_KEY}
   
     service:
       pipelines:
         metrics/host:
           receivers: [hostmetrics]
           processors:
             - memory_limiter
             - metricstransform
             - filter/exclude_cpu_utilization
             - filter/exclude_memory_utilization
             - filter/exclude_memory_usage
             - filter/exclude_filesystem_utilization
             - filter/exclude_filesystem_usage
             - filter/exclude_filesystem_inodes_usage
             - filter/exclude_system_disk
             - filter/exclude_network
             - attributes/exclude_system_paging
             - transform/host
             - resourcedetection
             - resourcedetection/cloud
             - resourcedetection/env
             - cumulativetodelta
             - batch
           exporters: [otlphttp]
         logs/host:
           receivers: [filelog]
           processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch]
           exporters: [otlphttp]
         traces:
           receivers: [otlp]
           processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch]
           exporters: [otlphttp]
         metrics:
           receivers: [otlp]
           processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch]
           exporters: [otlphttp]
         logs:
           receivers: [otlp]
           processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch]
           exporters: [otlphttp]
       extensions: [health_check]

   Copy

4. Create a new deployment adding the just-created remote configurations to your fleet. Agent Control will automatically apply the new configuration to your host, download and install the OCI packages for each of the agents. Follow these steps in create and run your first deployment.

5. Verify data is flowing. Navigate to Infrastructure > Hosts in the New Relic UI. Your host should appear within 1–2 minutes. If it does not appear, see Agent Control troubleshooting.

Windows

1. Create a fleet of type Windows Host in Fleet Control. See Create your first fleet for detailed steps.

2. Install Agent Control. Follow the Windows installation guide and select the fleet you created in Step 1.

3. Create configurations in Fleet Control for each of your agents. After Agent Control connects to Fleet Control, create configurations for each of your agents.

   Example adding the Infrastructure Agent, nri-mysql, nri-flex, fluentbit and nrdot, each of these configurations should be created as a separate remote configuration in Fleet Control:

   Infrastructure agent (baseline)

   config_agent contains the minimum required configuration. license_key is resolved at runtime from the NEW_RELIC_LICENSE_KEY environment variable using the nr-env value provider; custom_attributes is optional but recommended for filtering. config_logging forwards the Windows event log to New Relic Logs.

   config_agent:
     license_key: '${nr-env:NEW_RELIC_LICENSE_KEY}'
     custom_attributes:
       env: production
   config_logging:
     windows-event-log.yml:
       logs:
         - name: windows-event-log
           winevtlog:
             channel: System
           attributes:
             logtype: windows_event_log

   Copy

   nri-mysql (on-host integration)

   Monitors a MySQL instance running on localhost. The password is resolved at runtime from the MYSQL_PASSWORD environment variable using the nr-env value provider.

   config:
     integrations:
       - name: nri-mysql
         env:
           HOSTNAME: localhost
           PORT: 3306
           USERNAME: newrelic
           PASSWORD: ${nr-env:MYSQL_PASSWORD}
           REMOTE_MONITORING: true
         interval: 30s

   Copy

   nri-flex with PowerShell command (on-host integration)

   Collects logical disk performance metrics using Get-CimInstance via PowerShell. This example demonstrates how nri-flex can run any PowerShell command and parse its JSON output as New Relic events. Requires PowerShell v3+.

   config:
     integrations:
       - name: nri-flex
         config:
           name: winDiskPerf
           apis:
             - event_type: WinDiskPerfSample
               shell: powershell
               commands:
                 - run: >
                     Get-CimInstance -ClassName Win32_PerfFormattedData_PerfDisk_LogicalDisk |
                     Select-Object -Property Name, PercentFreeSpace, FreeMegabytes |
                     ConvertTo-Json

   Copy

   NRDOT (OpenTelemetry collector)

   Collects host metrics and opens an OTLP receiver for APM services. The license key and OTLP endpoint are injected automatically by Agent Control.

   config:
     # Variables set automatically by Agent Control:
     # - NEW_RELIC_LICENSE_KEY: New Relic ingest license key.
     # - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint (see: https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/).
   
     extensions:
       health_check:
   
     receivers:
       otlp:
         protocols:
           grpc:
           http:
   
       hostmetrics:
         collection_interval: 60s
         scrapers:
           cpu:
             metrics:
               system.cpu.time:
                 enabled: false
               system.cpu.utilization:
                 enabled: true
           load:
           memory:
             metrics:
               system.memory.utilization:
                 enabled: true
           paging:
             metrics:
               system.paging.utilization:
                 enabled: false
               system.paging.faults:
                 enabled: false
           filesystem:
             metrics:
               system.filesystem.utilization:
                 enabled: true
           disk:
             metrics:
               system.disk.merged:
                 enabled: false
               system.disk.pending_operations:
                 enabled: false
               system.disk.weighted_io_time:
                 enabled: false
           network:
             metrics:
               system.network.connections:
                 enabled: false
   
     processors:
       metricstransform:
         transforms:
           - include: system.cpu.utilization
             action: update
             operations:
               - action: aggregate_labels
                 label_set: [state]
                 aggregation_type: mean
           - include: system.paging.operations
             action: update
             operations:
               - action: aggregate_labels
                 label_set: [direction]
                 aggregation_type: sum
       filter/exclude_cpu_utilization:
         metrics:
           datapoint:
             - 'metric.name == "system.cpu.utilization" and attributes["state"] == "interrupt"'
             - 'metric.name == "system.cpu.utilization" and attributes["state"] == "nice"'
             - 'metric.name == "system.cpu.utilization" and attributes["state"] == "softirq"'
       filter/exclude_memory_utilization:
         metrics:
           datapoint:
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_unreclaimable"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "inactive"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "cached"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "buffered"'
             - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_reclaimable"'
       filter/exclude_memory_usage:
         metrics:
           datapoint:
             - 'metric.name == "system.memory.usage" and attributes["state"] == "slab_unreclaimable"'
             - 'metric.name == "system.memory.usage" and attributes["state"] == "inactive"'
       filter/exclude_filesystem_utilization:
         metrics:
           datapoint:
             - 'metric.name == "system.filesystem.utilization" and attributes["type"] == "squashfs"'
       filter/exclude_filesystem_usage:
         metrics:
           datapoint:
             - 'metric.name == "system.filesystem.usage" and attributes["type"] == "squashfs"'
             - 'metric.name == "system.filesystem.usage" and attributes["state"] == "reserved"'
       filter/exclude_filesystem_inodes_usage:
         metrics:
           datapoint:
             - 'metric.name == "system.filesystem.inodes.usage" and attributes["type"] == "squashfs"'
             - 'metric.name == "system.filesystem.inodes.usage" and attributes["state"] == "reserved"'
       filter/exclude_system_disk:
         metrics:
           datapoint:
             - 'metric.name == "system.disk.operations" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.merged" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.io" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.io_time" and IsMatch(attributes["device"], "^loop.*") == true'
             - 'metric.name == "system.disk.operation_time" and IsMatch(attributes["device"], "^loop.*") == true'
       filter/exclude_system_paging:
         metrics:
           datapoint:
             - 'metric.name == "system.paging.usage" and attributes["state"] == "cached"'
             - 'metric.name == "system.paging.operations" and attributes["type"] == "cached"'
       filter/exclude_network:
         metrics:
           datapoint:
             - 'IsMatch(metric.name, "^system.network.*") == true and attributes["device"] == "lo"'
       attributes/exclude_system_paging:
         include:
           match_type: strict
           metric_names:
             - system.paging.operations
         actions:
           - key: type
             action: delete
       cumulativetodelta:
       transform/host:
         metric_statements:
           - context: metric
             statements:
               - set(description, "")
               - set(unit, "")
       transform:
         trace_statements:
           - context: span
             statements:
               - truncate_all(attributes, 4095)
               - truncate_all(resource.attributes, 4095)
         log_statements:
           - context: log
             statements:
               - truncate_all(attributes, 4095)
               - truncate_all(resource.attributes, 4095)
       memory_limiter:
         check_interval: 1s
         limit_mib: 100
       batch:
       resourcedetection:
         detectors: ["system"]
         system:
           hostname_sources: ["os"]
           resource_attributes:
             host.id:
               enabled: true
       resourcedetection/cloud:
         detectors: ["gcp", "ec2", "azure"]
         timeout: 2s
         ec2:
           resource_attributes:
             host.name:
               enabled: false
       resourcedetection/env:
         detectors: ["env"]
         timeout: 2s
         override: true
   
     exporters:
       otlphttp:
         endpoint: ${nr-env:OTEL_EXPORTER_OTLP_ENDPOINT}
         headers:
           api-key: ${nr-env:NEW_RELIC_LICENSE_KEY}
   
     service:
       pipelines:
         metrics/host:
           receivers: [hostmetrics]
           processors:
             - memory_limiter
             - metricstransform
             - filter/exclude_cpu_utilization
             - filter/exclude_memory_utilization
             - filter/exclude_memory_usage
             - filter/exclude_filesystem_utilization
             - filter/exclude_filesystem_usage
             - filter/exclude_filesystem_inodes_usage
             - filter/exclude_system_disk
             - filter/exclude_network
             - attributes/exclude_system_paging
             - transform/host
             - resourcedetection
             - resourcedetection/cloud
             - resourcedetection/env
             - cumulativetodelta
             - batch
           exporters: [otlphttp]
         traces:
           receivers: [otlp]
           processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch]
           exporters: [otlphttp]
         metrics:
           receivers: [otlp]
           processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch]
           exporters: [otlphttp]
         logs:
           receivers: [otlp]
           processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch]
           exporters: [otlphttp]
       extensions: [health_check]

   Copy

4. Create a new deployment adding the just-created remote configurations to your fleet. Agent Control will automatically apply the new configuration to your host, download and install the OCI packages for each of the agents. Follow these steps in create and run your first deployment.

5. Verify data is flowing. Navigate to Infrastructure > Hosts in the New Relic UI. Your host should appear within 1–2 minutes. If it does not appear, see Agent Control troubleshooting.

If you already have agents installed, refer to Migrate to Agent Control instead.