Skip to content

[Do Not Merge] feat(ebpf ga): eBPF eAPM GA and eBPF Network Monitoring PP release docs #22047

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 13 commits into
base: develop
Choose a base branch
from
Draft

[Do Not Merge] feat(ebpf ga): eBPF eAPM GA and eBPF Network Monitoring PP release docs #22047

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
b2b373f
ebpf ga
WriteMayur Oct 30, 2025
a18fdf5
Merge branch 'develop' into ebpf-ga
WriteMayur Oct 30, 2025
cec3043
merge conflict
WriteMayur Oct 30, 2025
875e5eb
improved overview
WriteMayur Oct 30, 2025
74305a1
added related article section
WriteMayur Oct 30, 2025
eb1b484
new best practice and troubleshooting
WriteMayur Nov 3, 2025
2528293
new troubleshooting and best practice information
WriteMayur Nov 3, 2025
0ecbd15
new updates
WriteMayur Nov 5, 2025
49d9823
added new information
WriteMayur Nov 10, 2025
7821b8a
new fixes
WriteMayur Nov 10, 2025
0523ea5
new fixes
WriteMayur Nov 10, 2025
2a82d56
nav-fix
WriteMayur Nov 10, 2025
0489d87
minor updates
WriteMayur Nov 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
196 changes: 196 additions & 0 deletions src/content/docs/ebpf/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
---
title: eBPF agent best practices guide
tags:
- New Relic solutions
- Best practices guides
- eBPF
metaDescription: Best practices to help you find problems faster and deliver a better experience to your customers with New Relic's eBPF solution.
freshnessValidatedDate: never
---

New Relic eBPF agent uses eBPF technology to provide APM functionality in a single agent with zero code instrumentation. This approach empowers platform engineering teams by eliminating the need for coordination with application teams for monitoring deployment.

## When to use eBPF-powered APM [#when-to-use-eapm]

* **Large-scale deployments:** When you have many applications that need monitoring deployed at scale and require "good enough" metrics without the overhead of individual language agents.
* **Unknown or unmodifiable workloads:** When the workload you want to monitor is written in an unknown programming language and/or cannot be modified.
* **Platform engineering efficiency:** When you want to deploy monitoring at scale without coordinating with individual application teams.
* **Linux-focused environments:** When you don't need to monitor Windows platforms, as eBPF works excellently on Linux in both Kubernetes and host environments.
* **No distributed tracing requirement:** When your monitoring needs don't require distributed tracing capabilities.

### eBPF vs traditional APM comparison [#comparison]

Understanding the differences between eBPF-powered APM and traditional APM agents helps you choose the right approach:

<table>
<thead>
<tr>
<th>Functionality</th>
<th>eBPF agent (eAPM)</th>
<th>APM agent</th>
</tr>
</thead>
<tbody>
<tr>
<td>Summary</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>Transaction</td>
<td>✅ (segment linking for Java, Go, Node.js)</td>
<td>✅</td>
</tr>
<tr>
<td>Database operations</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>Service map</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>Distributed tracing</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>Programming language agnostic</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>Custom instrumentation</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>Auto-discover apps and services continuously</td>
<td>✅</td>
<td>❌</td>
</tr>
<tr>
<td>Linux support</td>
<td>✅</td>
<td>✅</td>
</tr>
<tr>
<td>Windows support</td>
<td>❌</td>
<td>✅</td>
</tr>
<tr>
<td>TCP and DNS telemetry</td>
<td>✅</td>
<td>❌</td>
</tr>
</tbody>
</table>

### Data source perspective

eBPF-powered APM shifts the monitoring perspective from the application layer to the kernel layer:

<table>
<thead>
<tr>
<th>Feature</th>
<th>APM language agent</th>
<th>eBPF-powered APM</th>
</tr>
</thead>
<tbody>
<tr>
<td>Data source</td>
<td>Application's memory / runtime hooks</td>
<td>Linux kernel (via eBPF)</td>
</tr>
<tr>
<td>Language dependency</td>
<td>High (requires specific agent for each language)</td>
<td>None (operates on kernel's view of process)</td>
</tr>
<tr>
<td>Code modification</td>
<td>Required</td>
<td>Not required (observes process from outside)</td>
</tr>
<tr>
<td>Outcome</td>
<td>Deep insight for known languages</td>
<td>Great insight for any workload on Linux (C++, Rust, etc.)</td>
</tr>
</tbody>
</table>

## Best practices for deployment [#deployment-best-practices]

### 1. Supplement the traditional APM

Use eBPF agent to supplement APM language agents for comprehensive coverage. This gives you full APM coverage with coexistence between eAPM and APM agents, without double data ingestion.

**Recommended approach:**
* **APM language agents:** Use for your most critical applications that require deep-level insights, distributed tracing, or custom instrumentation.
* **eBPF-powered APM:** Use to cover everything else, including uninstrumented services, third-party apps, and for continuously discovering/reporting new services.


### 2. Add network metrics for deeper context

<Callout title="Preview">
We're still working on eBPF network metrics capability, 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](/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy/). It is not available to customers subject to HIPAA or FedRAMP regulations.
</Callout>


The eBPF agent can also provide granular network metrics (TCP, DNS, etc.) to give you visibility outside your application's boundary. This capability is complementary and can be used with or without eAPM. For more information, refer to [network-metrics](/docs/ebpf/network-metrics/).

The following deployment options are available:

<table>
<thead>
<tr>
<th>Application metric source</th>
<th>Network metric source</th>
<th>Configuration</th>
</tr>
</thead>
<tbody>
<tr>
<td>APM language agent</td>
<td>eBPF agent (network metrics only mode)</td>
<td>Two agents</td>
</tr>
<tr>
<td>eBPF agent (eAPM)</td>
<td>eBPF agent (same agent)</td>
<td>Single agent</td>
</tr>
</tbody>
</table>

### 3. Create a unified monitoring approach

By following the practices above, you can use the single eBPF agent to handle both infrastructure and application monitoring needs. This unifies your observability, allowing the agent to automatically gather critical application performance data (eAPM) and network metrics (eBPF network metrics) to populate existing dashboards, providing deep context without code changes or restarts.

**Benefits:**
* APM insights that populate New Relic APM UI automatically.
* Network insights from the same agent.


## Implementation recommendations [#implementation-recommendations]

* **Start with eAPM for scale:** If you need to deploy monitoring at scale across many applications and want "good enough" metrics without complex coordination, start with eBPF-powered APM.

* **Add network metrics for complete visibility:** Once eAPM is deployed, consider adding eBPF network metrics to gain visibility beyond application boundaries for comprehensive troubleshooting capabilities.


## Related articles [#related-articles]

<DocTiles>
<DocTile title="eBPF Kubernetes installation" path="/docs/ebpf/k8s-installation/">Learn how to set up the New Relic eBPF agent for your Kubernetes cluster.</DocTile>
<DocTile title="eBPF Linux installation" path="/docs/ebpf/linux-installation/">Learn how to set up the New Relic eBPF agent for your Linux host.</DocTile>
<DocTile title="Troubleshooting eBPF" path="/docs/ebpf/troubleshooting/no-ui-data/">Learn how to troubleshoot issues with the New Relic eBPF agent.</DocTile>
</DocTiles>
100 changes: 67 additions & 33 deletions src/content/docs/ebpf/k8s-installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Install and configure New Relic eBPF integration"
metaDescription: "Learn how to install and configure the New Relic eBPF agent for your Linux host and Kubernetes cluster."
title: "Install New Relic eBPF agent for Kubernetes"
metaDescription: "Learn how to install and configure the New Relic eBPF agent for your Kubernetes cluster using Helm charts."
tags:
- New Relic integrations with eBPF
- New Relic eBPF agent
Expand All @@ -11,20 +11,25 @@ tags:
freshnessValidatedDate: never
---

<Callout title="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](/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy/). It is not available to customers subject to HIPAA or FedRAMP regulations.
</Callout>

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

## Compatibility and requirements [#requirements]
## Install New Relic eBPF agent

<Steps>

<Step>

### Before you begin [#requirements]

* Ensure that all [Kubernetes integration compatibility and requirements](/docs/kubernetes-pixie/kubernetes-integration/get-started/kubernetes-integration-compatibility-requirements/) are met.
You must meet the prerequisites outlined in the [eBPF compatibility and requirements](/docs/ebpf/requirements#k8s) documentation for Kubernetes clusters.

</Step>

## Install the eBPF agent [#install]
<Step>


### Install the eBPF agent [#install]

To install the eBPF agent:

Expand All @@ -43,6 +48,10 @@ To install the eBPF agent:
2. (Optional) Enter the namespace for the integration. The default namespace is `newrelic`.
3. Click **Continue**.

<Callout variant="tip">
If you choose a custom namespace for your New Relic instrumentation (instead of the default `newrelic`), we recommend excluding that namespace from monitoring by adding it to the `dropDataForNamespaces` configuration parameter. This prevents the eBPF agent from monitoring the instrumentation pods themselves. For example, if you use `newrelic-mon` as your namespace, set: `dropDataForNamespaces: ["kube-system", "newrelic-mon"]`.
</Callout>

7. On the Install the Kubernetes integration screen:

1. Copy and paste the displayed command to install the eBPF agent on your Kubernetes cluster using Helm.
Expand All @@ -59,8 +68,11 @@ To install the eBPF agent:
kubectl get pods -n newrelic
```

</Step>

## Access the eBPF data in New Relic [#access-data]
<Step>

### Access the eBPF data in New Relic [#access-data]

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](/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-ui).

Expand All @@ -75,29 +87,9 @@ Once the eBPF agent is installed, it automatically starts collecting data from y
src="/images/ebpf_filters.webp"
/>

### Configure the eBPF Dashboard [#ebpf-dashboard]

The eBPF Network dashboard provides deep visibility into your system's network health by tracking critical DNS and TCP metrics directly from the kernel. You can diagnose connectivity issues by analyzing success and failure rates for DNS resolutions and TCP connections. Pinpoint performance bottlenecks by monitoring key latencies like TCP handshakes, packet delivery, and the duration of short-lived connections. The dashboard also helps you track data throughput by visualizing bytes sent, received, and any packets dropped.

To configure the eBPF network dashboard:

1. Go to **[one.newrelic.com](https://one.newrelic.com) > Dashboards**.
2. In the **Dashboards**, click **+ Create a dashboard**.
3. In the **Create a dashboard** window, click **Browse pre-built dashboards**.
4. In the search bar, type **eBPF** and select the **eBPF**.
5. *(Optional)* In the displayed window, click **Edit** to change the account.
6. Click **Setup eBPF Agent** to setup the data source or click **Skip this step** if the eBPF agent is already setup.
7. Click **View dashboard** to view the data collected by the eBPF agent.

<Callout variant="tip">

The eBPF agent automatically generates entity names differently depending on the environment:

* In hosts or Docker, names are a combination of the process name, its directory or container ID, and the listening port. For example, `ruby:/home/ubuntu/app:[5678]` or `java:f4aead533895:[8080]`.
</Step>

* In Kubernetes, names are derived from the service name for example, `mysql-database-service`.

</Callout>
</Steps>

{/*
Once your app is instrumented and configured to export data to New Relic, you should be able to find your data in the New Relic UI:
Expand All @@ -112,6 +104,25 @@ You can find the data collected by the eBPF agent in the New Relic Opentelementr
*/}


## Upgrade the eBPF agent [#upgrade]

To upgrade the eBPF agent in a Kubernetes cluster:

* **For a standard upgrade**: Use the following Helm command to upgrade to the latest version:

```bash
KSM_IMAGE_VERSION="v2.13.0" && helm repo add newrelic https://helm-charts.newrelic.com && helm repo update && kubectl create namespace "newrelic" ; helm upgrade --install nr-ebpf-agent newrelic/nr-ebpf-agent --set licenseKey=<key> --set cluster="<cluster-name>" --namespace=newrelic
```

* **For a specific version upgrade:** To upgrade to a specific version, use the `--version` flag:

```bash
KSM_IMAGE_VERSION="v2.13.0" && helm repo add newrelic https://helm-charts.newrelic.com && helm repo update && kubectl create namespace "newrelic" ; helm upgrade --install nr-ebpf-agent newrelic/nr-ebpf-agent --set licenseKey=<key> --set cluster="<cluster-name>" --namespace=newrelic --version=0.2.5
```

Replace `<key>` with your New Relic license key and `<cluster-name>` with your cluster name.


## Configuration parameters [#config-params]

The [`values.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-ebpf-agent/values.yaml) file contains the following configuration sections:
Expand Down Expand Up @@ -523,3 +534,26 @@ This section configures secure communication between the eBPF agent and client c
</Collapser>

</CollapserGroup>





## Uninstall the eBPF agent [#uninstall]

To uninstall the eBPF agent from your Kubernetes cluster:

```bash
helm uninstall nr-ebpf-agent -n newrelic
```

<Callout variant="tip">
This command will remove all eBPF agent components from your cluster. The namespace will remain unless you explicitly delete it.
</Callout>


<DocTiles>
<DocTile title="eBPF Linux installation" path="/docs/ebpf/linux-installation/">Learn how to set up the New Relic eBPF agent for your Linux host.</DocTile>
<DocTile title="Troubleshooting eBPF" path="/docs/ebpf/troubleshooting/no-ui-data/">Learn how to troubleshoot issues with the New Relic eBPF agent.</DocTile>
<DocTile title="eBPF best practices" path="/docs/ebpf/best-practices/">Learn about best practices for using the New Relic eBPF agent.</DocTile>
</DocTiles>
Loading