Install New Relic eBPF agent for Linux hosts

You can install the New Relic eBPF agent on your Linux host to monitor your entire system health. The eBPF agent provides deep visibility into application performance without requiring code changes or deploying language-specific agents.

Install the New Relic eBPF agent

Before you begin

You must meet the prerequisites outlined in the eBPF compatibility and requirements documentation for Linux hosts.

Install the eBPF agent

To install the eBPF agent:

Log in to your New Relic account.
Go to left navigation pane > + Integration & Agents > eBPF Agent.
On the Select an account screen, select the account you want to install the eBPF agent on, and click Continue.
On the Select an installation method page, select On a host, and click Continue.
On the Enter your user key screen, select one of the following options, then click Continue:
- Use an existing key: If you already have a user key, provide the user key. For more information, refer to User keys.
- Create a new key: If you don't have a user key, click Create a new key to create one.
On the Configure the host integration screen, enter the deployment name for host, then click Continue.
On the Install the agent screen, run the provided command in your terminal to install the eBPF agent via Debian package.
1. Copy and paste the displayed command to install the eBPF agent on your Debian host.
2. To verify the installation, run the following command:
  bash
```
$sudo systemctl status newrelic-ebpf-agent
$```    
$Upon successful installation, the status of these services display as active (running).
```
Dica
You can customize the eBPF agent configuration by editing the newrelic-ebpf-agent.conf file available at /etc/newrelic-ebpf-agent/newrelic-ebpf-agent.conf. For more information on the configuration parameters, refer to Configuration parameters.

Access the eBPF data in New Relic

Once the eBPF agent is installed, it automatically starts collecting data from your Linux host. You can access this data in New Relic's OpenTelemetry UI. For more information on New Relic OpenTelemetry UI, refer OpenTelemetry APM UI.

To view the eBPF data in New Relic:

Go to one.newrelic.com > APM & Services.
In the search banner, set the search criteria as instrumentation.name = nr_ebpf:

Upgrade the eBPF agent

To upgrade the eBPF agent on a Linux host, re-execute the installation command from the New Relic UI. This process will install the new agent version while automatically removing the older one.

Importante

Upgrading through a package manager is not supported. You must use the installation command from the New Relic UI for a successful upgrade.

To get the latest installation command:

Go to one.newrelic.com > + Integration & Agents > eBPF Agent
Follow the installation flow to get the updated command
Run the command on your host to upgrade the agent
Restart the ebpf agent service using the below command:
bash
```
$sudo systemctl restart newrelic-ebpf-agent
```

Configuration parameters

The newrelic-ebpf-agent.conf file contains the following configuration parameters:

Parameter name	Description	Data type	Example value
`NEW_RELIC_LICENSE_KEY`	Specifies your New Relic license key, which is required to send data.	`String`	`22387565c...FFFFNRAL`
`DEPLOYMENT_NAME`	Specifies a unique name for your deployment to help identify its data in New Relic.	`String`	`fe`
`OTLP_ENDPOINT`	Defines the OTLP endpoint where the agent sends telemetry data.	`String (Host:Port)`	`otlp.nr-data.net:443`
`NEW_RELIC_LOG_LEVEL`	Sets the agent's log level. Options are `OFF`, `FATAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` in increasing order of verbosity.	`String`	`INFO`
`NEW_RELIC_LOG_FILE_PATH`	Specifies the file path for agent logs. If empty or the path is invalid, logs are sent to standard output (stdout).	`String (Path)`	`""`
`APM_DATA_REPORTING`	Enable APM data reporting. When enabled, the agent collects and reports application performance monitoring data.	`String`	`"true"`
`DROP_NETWORK_METRICS_DATA_FOR_ENTITY_NAME`	Comma-separated list of entity names for dropping Network metrix data. For example: `"kube-dns,otel-collector,service1"`.	`String`	`""`
`KEEP_NETWORK_METRICS_DATA_FOR_ENTITY_NAME`	Comma-separated list of entity names to always keep Network metrix data. default all entity is keepd/enabled. This bypasses DROP_NETWORK_METRICS_DATA_FOR_ENTITY_NAME filter. For example: `"critical-service,important-app,must-monitor"`.	`String`	`""`
`DROP_APM_DATA_FOR_ENTITY_NAME`	Comma-separated list of entity names for dropping eBPF APM data. For example: `"kube-dns,otel-collector,service1"`.	`String`	`""`
`KEEP_APM_DATA_FOR_ENTITY_NAME`	Comma-separated list of entity names to always keep eBPF APM data. default all entity is keepd/enabled. This bypasses `DROP_APM_DATA_FOR_ENTITY_NAME` filter. For example: `"critical-service,important-app,must-monitor"`.	`String`	`""`
`DROP_EAPM_DATA_FOR_APM_AGENT_ENABLED_ENTITY`	Drop eBPF APM data for applications/entities that have NewRelic/OpenTelemetry APM agents running	`String`	`"true"`
`DROP_ALL_DATA_FOR_ENTITY_NAME_REGEX`	Regular expression pattern to match entity names for dropping ALL data (TCP stats + APM data). For example: `"java-app\|otel-collector\|\\bservice1\\b"`	`String`	`""`
`KEEP_ALL_DATA_FOR_ENTITY_NAME_REGEX`	Regular expression pattern to match entity names to always keep ALL data for. This bypasses all drop filters. For example: `"critical-service\|important-app\|\\bmust-monitor\\b"`	`String`	`""`
`DROP_ALL_DATA_FOR_APM_AGENT_ENABLED_ENTITY`	Drop all data for applications/entities that have NewRelic/OpenTelemetry APM agents running.	`String`	`"false"`
`INCLUDE_PORT_IN_SERVER_ENTITY_IDENTIFICATION`	The configuration allows you to include or exclude ports from auto-discovered entity names. Typically, names appear as `processName:cwd/container_name:[port]`, e.g., `python:frosty_merkle:[80]`. To exclude port details, set this option to `false` for names such as `python:frosty_merkle`.	`String`	`"true"`
`TABLE_STORE_DATA_LIMIT_MB`	Sets the maximum memory (in MiB) that the eBPF agent can use for its internal data table store. This is the primary way to control the agent's RAM usage.	Integer	`250`
`DOWNLOADED_PACKAGED_HEADERS_PATH`	Sets the absolute path of the complete directory where the required linux headers are manually downloaded and placed for the eBPF agent to use. This is useful under restricted environments where agent is not able to download required linux headers. The required headers are identified by the agent based on the kernel version. Use only after NR support recommendation.	`String (Path)`	`"/path/to/downloaded/headers/dir"`
`DISTRO_KERNEL_HEADERS_PATH`	Sets the absolute path of the complete directory where the linux headers are present for the eBPF agent to use. This is useful where required linux headers could not be installed or path could not be determined. Use only after NR support recommendation.	`String (Path)`	`"/usr/src/kernels"`
`PROTOCOLS_SPANS_UNLINKED_MAX`	Controls maximum unlinked spans reported per protocol. Set to 0 to disable limit.	`String`	`"100"`
`PROTOCOLS_HTTP_ENABLED`	Enables or disables all HTTP protocol tracing (metrics and spans).	`String`	`"true"`
`PROTOCOLS_HTTP_SPANS_ENABLED`	Enables or disables the exporting of spans for HTTP requests.	`String`	`"true"`
`PROTOCOLS_HTTP_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting HTTP spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_HTTP_SPANS_SAMPLING_ERROR_RATE`	Sets an error rate percentage (1-100) for an HTTP route. If a route's error rate exceeds this value, its corresponding spans are exported.	`String`	`""`
`PROTOCOLS_MYSQL_ENABLED`	Enables or disables all MySQL protocol tracing.	`String`	`"true"`
`PROTOCOLS_MYSQL_SPANS_ENABLED`	Enables or disables exporting of spans for MySQL queries.	`String`	`"false"`
`PROTOCOLS_MYSQL_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting MySQL spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_PGSQL_ENABLED`	Enables or disables all PostgreSQL protocol tracing.	`String`	`"true"`
`PROTOCOLS_PGSQL_SPANS_ENABLED`	Enables or disables exporting of spans for PostgreSQL queries.	`String`	`"false"`
`PROTOCOLS_PGSQL_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting PostgreSQL spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_CASS_ENABLED`	Enables or disables all Cassandra protocol tracing.	`String`	`"true"`
`PROTOCOLS_CASS_SPANS_ENABLED`	Enables or disables exporting of spans for Cassandra queries.	`String`	`"false"`
`PROTOCOLS_CASS_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting Cassandra spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_REDIS_ENABLED`	Enables or disables all Redis protocol tracing.	`String`	`"true"`
`PROTOCOLS_REDIS_SPANS_ENABLED`	Enables or disables exporting of spans for Redis commands.	`String`	`"false"`
`PROTOCOLS_REDIS_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting Redis spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_MONGODB_ENABLED`	Enables or disables all MongoDB protocol tracing.	`String`	`"true"`
`PROTOCOLS_MONGODB_SPANS_ENABLED`	Enables or disables exporting of spans for MongoDB queries.	`String`	`"false"`
`PROTOCOLS_MONGODB_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting MongoDB spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_DYNAMODB_ENABLED`	Enables or disables all DynamoDB protocol tracing.	`String`	`"true"`
`PROTOCOLS_DYNAMODB_SPANS_ENABLED`	Enables or disables exporting of spans for DynamoDB queries.	`String`	`"false"`
`PROTOCOLS_DYNAMODB_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting DynamoDB spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_MSSQL_ENABLED`	Enables or disables all MSSQL protocol tracing.	`String`	`"true"`
`PROTOCOLS_MSSQL_SPANS_ENABLED`	Enables or disables exporting of spans for MSSQL queries.	`String`	`"false"`
`PROTOCOLS_MSSQL_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting MSSQL spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_KAFKA_ENABLED`	Enables or disables all Kafka protocol tracing.	`String`	`"true"`
`PROTOCOLS_KAFKA_SPANS_ENABLED`	Enables or disables exporting of spans for Kafka messages. Note: Kafka tracing does not report metrics.	`String`	`"true"`
`PROTOCOLS_KAFKA_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting Kafka spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_AMQP_ENABLED`	Enables or disables all AMQP protocol tracing.	`String`	`"true"`
`PROTOCOLS_AMQP_SPANS_ENABLED`	Enables or disables exporting of spans for AMQP (e.g., RabbitMQ) messages. Note: AMQP tracing does not report metrics.	`String`	`"true"`
`PROTOCOLS_AMQP_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting AMQP spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`
`PROTOCOLS_DNS_ENABLED`	Enables or disables all DNS protocol tracing.	`String`	`"true"`
`PROTOCOLS_DNS_SPANS_ENABLED`	Enables or disables exporting of spans for DNS queries. Note: DNS tracing does not report metrics.	`String`	`"true"`
`PROTOCOLS_DNS_SPANS_SAMPLING_LATENCY`	Sets the sampling latency threshold for exporting DNS spans. Spans for requests slower than this percentile are exported. Options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p50"`

Uninstall the eBPF agent

To uninstall the eBPF agent from a Linux host, use your system's package management tools:

bash

$sudo apt-get remove newrelic-ebpf-agent

Dica

It is not necessary to stop the service before running the uninstall command.

eBPF Kubernetes installation

Learn how to set up the New Relic eBPF agent for your Kubernetes cluster.

Troubleshooting eBPF

Learn how to troubleshoot issues with the New Relic eBPF agent.

eBPF best practices

Learn about best practices for using the New Relic eBPF agent.

Install New Relic eBPF agent for Linux hosts

Install the New Relic eBPF agent.css-21sua1{background:none;border:none;width:0;padding:0;}

Before you begin

Install the eBPF agent

Dica

Access the eBPF data in New Relic

Upgrade the eBPF agent

Importante

Configuration parameters

Uninstall the eBPF agent

Dica

eBPF Kubernetes installation

Troubleshooting eBPF

eBPF best practices

Install the New Relic eBPF agent