Skip to content

Commit d244169

Browse files
WriteMayurWriteMayur
authored
Merge pull request #22047 from newrelic/ebpf-ga
feat(ebpf ga): eBPF eAPM GA and eBPF Network Monitoring PP release docs
2 parents 9f79549 + 59c1e00 commit d244169

File tree

17 files changed

+1408
-2419
lines changed

17 files changed

+1408
-2419
lines changed

‎src/content/docs/ebpf/best-practices.mdx‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: eBPF agent best practices guide
3+
tags:
4+
- New Relic solutions
5+
- Best practices guides
6+
- eBPF
7+
metaDescription: Best practices to help you find problems faster and deliver a better experience to your customers with New Relic's eBPF solution.
8+
freshnessValidatedDate: never
9+
---
10+
11+
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.
12+
13+
## When to use eBPF-powered APM [#when-to-use-eapm]
14+
15+
* **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.
16+
* **Unknown or unmodifiable workloads:** When the workload you want to monitor is written in an unknown programming language and/or cannot be modified.
17+
* **Platform engineering efficiency:** When you want to deploy monitoring at scale without coordinating with individual application teams.
18+
* **Linux-focused environments:** When you don't need to monitor Windows platforms, as eBPF works excellently on Linux in both Kubernetes and host environments.
19+
* **No distributed tracing requirement:** When your monitoring needs don't require distributed tracing capabilities.
20+
21+
### eBPF vs traditional APM comparison [#comparison]
22+
23+
Understanding the differences between eBPF-powered APM and traditional APM agents helps you choose the right approach:
24+
25+
<table>
26+
<thead>
27+
<tr>
28+
<th>Functionality</th>
29+
<th>eBPF agent (eAPM)</th>
30+
<th>APM agent</th>
31+
</tr>
32+
</thead>
33+
<tbody>
34+
<tr>
35+
<td>Summary</td>
36+
<td>✅</td>
37+
<td>✅</td>
38+
</tr>
39+
<tr>
40+
<td>Transaction</td>
41+
<td>✅ (segment linking for Java, Go, Node.js)</td>
42+
<td>✅</td>
43+
</tr>
44+
<tr>
45+
<td>Database operations</td>
46+
<td>✅</td>
47+
<td>✅</td>
48+
</tr>
49+
<tr>
50+
<td>Service map</td>
51+
<td>✅</td>
52+
<td>✅</td>
53+
</tr>
54+
<tr>
55+
<td>Distributed tracing</td>
56+
<td>❌</td>
57+
<td>✅</td>
58+
</tr>
59+
<tr>
60+
<td>Programming language agnostic</td>
61+
<td>✅</td>
62+
<td>❌</td>
63+
</tr>
64+
<tr>
65+
<td>Custom instrumentation</td>
66+
<td>❌</td>
67+
<td>✅</td>
68+
</tr>
69+
<tr>
70+
<td>Auto-discover apps and services continuously</td>
71+
<td>✅</td>
72+
<td>❌</td>
73+
</tr>
74+
<tr>
75+
<td>Linux support</td>
76+
<td>✅</td>
77+
<td>✅</td>
78+
</tr>
79+
<tr>
80+
<td>Windows support</td>
81+
<td>❌</td>
82+
<td>✅</td>
83+
</tr>
84+
<tr>
85+
<td>TCP and DNS telemetry</td>
86+
<td>✅</td>
87+
<td>❌</td>
88+
</tr>
89+
</tbody>
90+
</table>
91+
92+
### Data source perspective
93+
94+
eBPF-powered APM shifts the monitoring perspective from the application layer to the kernel layer:
95+
96+
<table>
97+
<thead>
98+
<tr>
99+
<th>Feature</th>
100+
<th>APM language agent</th>
101+
<th>eBPF-powered APM</th>
102+
</tr>
103+
</thead>
104+
<tbody>
105+
<tr>
106+
<td>Data source</td>
107+
<td>Application's memory / runtime hooks</td>
108+
<td>Linux kernel (via eBPF)</td>
109+
</tr>
110+
<tr>
111+
<td>Language dependency</td>
112+
<td>High (requires specific agent for each language)</td>
113+
<td>None (operates on kernel's view of process)</td>
114+
</tr>
115+
<tr>
116+
<td>Code modification</td>
117+
<td>Required</td>
118+
<td>Not required (observes process from outside)</td>
119+
</tr>
120+
<tr>
121+
<td>Outcome</td>
122+
<td>Deep insight for known languages</td>
123+
<td>Great insight for any workload on Linux (C++, Rust, etc.)</td>
124+
</tr>
125+
</tbody>
126+
</table>
127+
128+
## Best practices for deployment [#deployment-best-practices]
129+
130+
### 1. Supplement the traditional APM
131+
132+
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.
133+
134+
**Recommended approach:**
135+
* **APM language agents:** Use for your most critical applications that require deep-level insights, distributed tracing, or custom instrumentation.
136+
* **eBPF-powered APM:** Use to cover everything else, including uninstrumented services, third-party apps, and for continuously discovering/reporting new services.
137+
138+
139+
### 2. Add network metrics for deeper context
140+
141+
<Callout title="Preview">
142+
We're still working on eBPF network metrics capability, but we'd love for you to try it out!
143+
144+
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.
145+
</Callout>
146+
147+
148+
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/).
149+
150+
The following deployment options are available:
151+
152+
<table>
153+
<thead>
154+
<tr>
155+
<th>Application metric source</th>
156+
<th>Network metric source</th>
157+
<th>Configuration</th>
158+
</tr>
159+
</thead>
160+
<tbody>
161+
<tr>
162+
<td>APM language agent</td>
163+
<td>eBPF agent (network metrics only mode)</td>
164+
<td>Two agents</td>
165+
</tr>
166+
<tr>
167+
<td>eBPF agent (eAPM)</td>
168+
<td>eBPF agent (same agent)</td>
169+
<td>Single agent</td>
170+
</tr>
171+
</tbody>
172+
</table>
173+
174+
### 3. Create a unified monitoring approach
175+
176+
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.
177+
178+
**Benefits:**
179+
* APM insights that populate New Relic APM UI automatically.
180+
* Network insights from the same agent.
181+
182+
183+
## Implementation recommendations [#implementation-recommendations]
184+
185+
* **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.
186+
187+
* **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.
188+
189+
190+
## Related articles [#related-articles]
191+
192+
<DocTiles>
193+
<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>
194+
<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>
195+
<DocTile title="Troubleshooting eBPF" path="/docs/ebpf/troubleshooting/no-ui-data/">Learn how to troubleshoot issues with the New Relic eBPF agent.</DocTile>
196+
</DocTiles>

‎src/content/docs/ebpf/k8s-installation.mdx‎

Lines changed: 67 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: "Install and configure New Relic eBPF integration"
3-
metaDescription: "Learn how to install and configure the New Relic eBPF agent for your Linux host and Kubernetes cluster."
2+
title: "Install New Relic eBPF agent for Kubernetes"
3+
metaDescription: "Learn how to install and configure the New Relic eBPF agent for your Kubernetes cluster using Helm charts."
44
tags:
55
- New Relic integrations with eBPF
66
- New Relic eBPF agent
@@ -11,20 +11,25 @@ tags:
1111
freshnessValidatedDate: never
1212
---
1313

14-
<Callout title="Preview">
15-
We're still working on this feature, but we'd love for you to try it out!
16-
17-
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.
18-
</Callout>
1914

2015
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.
2116

22-
## Compatibility and requirements [#requirements]
17+
## Install New Relic eBPF agent
18+
19+
<Steps>
20+
21+
<Step>
22+
23+
### Before you begin [#requirements]
24+
25+
You must meet the prerequisites outlined in the [eBPF compatibility and requirements](/docs/ebpf/requirements#k8s) documentation for Kubernetes clusters.
2326

24-
* Ensure that all [Kubernetes integration compatibility and requirements](/docs/kubernetes-pixie/kubernetes-integration/get-started/kubernetes-integration-compatibility-requirements/) are met.
27+
</Step>
2528

29+
<Step>
2630

27-
## Install the eBPF agent [#install]
31+
32+
### Install the eBPF agent [#install]
2833

2934
To install the eBPF agent:
3035

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

51+
<Callout variant="tip">
52+
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"]`.
53+
</Callout>
54+
4655
7. On the Install the Kubernetes integration screen:
4756

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

71+
</Step>
72+
73+
<Step>
6274

63-
## Access the eBPF data in New Relic [#access-data]
75+
### Access the eBPF data in New Relic [#access-data]
6476

6577
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).
6678

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

78-
### Configure the eBPF Dashboard [#ebpf-dashboard]
79-
80-
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.
81-
82-
To configure the eBPF network dashboard:
90+
</Step>
8391

84-
1. Go to **[one.newrelic.com](https://one.newrelic.com) > Dashboards**.
85-
2. In the **Dashboards**, click **+ Create a dashboard**.
86-
3. In the **Create a dashboard** window, click **Browse pre-built dashboards**.
87-
4. In the search bar, type **eBPF** and select the **eBPF**.
88-
5. *(Optional)* In the displayed window, click **Edit** to change the account.
89-
6. Click **Setup eBPF Agent** to setup the data source or click **Skip this step** if the eBPF agent is already setup.
90-
7. Click **View dashboard** to view the data collected by the eBPF agent.
91-
92-
<Callout variant="tip">
93-
94-
The eBPF agent automatically generates entity names differently depending on the environment:
95-
96-
* In hosts or Docker, these names are a combination of the process name, its directory or container name, and the listening port. For example, `ruby:/home/ubuntu/app:[5678]` or `java:my-container-name:[8080]`.
97-
98-
* In Kubernetes, names are derived from the service name for example, `mysql-database-service`.
99-
100-
</Callout>
92+
</Steps>
10193

10294
{/*
10395
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:
@@ -112,6 +104,25 @@ You can find the data collected by the eBPF agent in the New Relic Opentelementr
112104
*/}
113105

114106

107+
## Upgrade the eBPF agent [#upgrade]
108+
109+
To upgrade the eBPF agent in a Kubernetes cluster:
110+
111+
* **For a standard upgrade**: Use the following Helm command to upgrade to the latest version:
112+
113+
```bash
114+
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
115+
```
116+
117+
* **For a specific version upgrade:** To upgrade to a specific version, use the `--version` flag:
118+
119+
```bash
120+
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
121+
```
122+
123+
Replace `<key>` with your New Relic license key and `<cluster-name>` with your cluster name.
124+
125+
115126
## Configuration parameters [#config-params]
116127

117128
The [`values.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-ebpf-agent/values.yaml) file contains the following configuration sections:
@@ -248,12 +259,6 @@ These parameters control which data is collected and sent to New Relic, helping
248259
<td>`Boolean`</td>
249260
<td>`true`</td>
250261
</tr>
251-
<tr>
252-
<td>`dropAPMEnabledPods`</td>
253-
<td>If `true`, drops telemetry from pods that are already monitored by a New Relic APM agent to avoid data duplication.</td>
254-
<td>`Boolean`</td>
255-
<td>`true`</td>
256-
</tr>
257262
<tr>
258263
<td>`dropDataForNamespaces`</td>
259264
<td>Specifies a list of Kubernetes namespaces from which all telemetry will be dropped.</td>
@@ -535,3 +540,26 @@ This section configures secure communication between the eBPF agent and client c
535540
</Collapser>
536541

537542
</CollapserGroup>
543+
544+
545+
546+
547+
548+
## Uninstall the eBPF agent [#uninstall]
549+
550+
To uninstall the eBPF agent from your Kubernetes cluster:
551+
552+
```bash
553+
helm uninstall nr-ebpf-agent -n newrelic
554+
```
555+
556+
<Callout variant="tip">
557+
This command will remove all eBPF agent components from your cluster. The namespace will remain unless you explicitly delete it.
558+
</Callout>
559+
560+
561+
<DocTiles>
562+
<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>
563+
<DocTile title="Troubleshooting eBPF" path="/docs/ebpf/troubleshooting/no-ui-data/">Learn how to troubleshoot issues with the New Relic eBPF agent.</DocTile>
564+
<DocTile title="eBPF best practices" path="/docs/ebpf/best-practices/">Learn about best practices for using the New Relic eBPF agent.</DocTile>
565+
</DocTiles>

0 commit comments

Comments
 (0)