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:
  - For eBPF agent:
    bash
```
$sudo systemctl status newrelic-ebpf-agent
```
  - For eBPF client:
    bash
```
$sudo systemctl status newrelic-ebpf-agent-client
```
Upon successful installation, the status of these services display as active (running).
Sugerencia
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

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)`	`""`
`VIZIER_PORT`	Vizier server port on which agent receives pxl scripts from the client. Default to 12345.	`String`	`"12345"`
`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.(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. (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. (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.(Example: "critical-service,important-app,must-monitor")	`String`	`""`
`DROP_APM_DATA_FOR_APM_AGENT_ENABLED_ENTITY`	Drop eBPF APM data for applications/entities that have NewRelic/OpenTelemetry APM agents running	`String`	`"false"`
`DROP_ALL_DATA_FOR_ENTITY_NAME_REGEX`	Regular expression pattern to match entity names for dropping ALL data (TCP stats + APM data)(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.(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 like `python:frosty_merkle`.	`String`	`"true"`
`TLS_ENABLED`	Enables or disables TLS for communication between the eBPF client and agent.	`String`	`"true"`
`TLS_AUTOGENERATE_CERT_ENABLED`	If set to `true`, automatically generates a self-signed certificate for TLS. Set to `false` if you are providing your own certificates.	`String`	`"true"`
`TLS_CERT_PATH`	Specifies the directory path where autogenerated TLS certificates are stored.	`String (Path)`	`/tmp/ebpf/certs/`
`TLS_CERT_FILE`	Specifies the path to your custom PEM-encoded public certificate file. Required if `TLS_AUTOGENERATE_CERT_ENABLED` is `false`.	`String (Path)`	`""`
`TLS_KEY_FILE`	Specifies the path to your custom PEM-encoded private key file. Required if `TLS_AUTOGENERATE_CERT_ENABLED` is `false`.	`String (Path)`	`""`
`TLS_CA_FILE`	Specifies the path to your custom PEM-encoded Certificate Authority (CA) file. Required if `TLS_AUTOGENERATE_CERT_ENABLED` is `false`.	`String (Path)`	`""`
`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_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_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_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_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_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_KAFKA_SPANS_ENABLED`	Enables or disables exporting of spans for Kafka messages. Note: Kafka tracing does not report metrics.	`String`	`"false"`
`PROTOCOLS_AMQP_SPANS_ENABLED`	Enables or disables exporting of spans for AMQP (e.g., RabbitMQ) messages. Note: AMQP tracing does not report metrics.	`String`	`"false"`
`PROTOCOLS_DNS_SPANS_ENABLED`	Enables or disables exporting of spans for DNS queries. Note: DNS tracing does not report metrics.	`String`	`"false"`

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

Sugerencia

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

Sugerencia

Access the eBPF data in New Relic

Upgrade the eBPF agent

Importante

Configuration parameters

Uninstall the eBPF agent

Sugerencia

eBPF Kubernetes installation

Troubleshooting eBPF

eBPF best practices

Install the New Relic eBPF agent