diff --git a/src/content/docs/ebpf/best-practices.mdx b/src/content/docs/ebpf/best-practices.mdx new file mode 100644 index 00000000000..7e14200b906 --- /dev/null +++ b/src/content/docs/ebpf/best-practices.mdx @@ -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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionalityeBPF agent (eAPM)APM agent
Summary✅✅
Transaction✅ (segment linking for Java, Go, Node.js)✅
Database operations✅✅
Service map✅✅
Distributed tracing❌✅
Programming language agnostic✅❌
Custom instrumentation❌✅
Auto-discover apps and services continuously✅❌
Linux support✅✅
Windows support❌✅
TCP and DNS telemetry✅❌
+ +### Data source perspective + +eBPF-powered APM shifts the monitoring perspective from the application layer to the kernel layer: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureAPM language agenteBPF-powered APM
Data sourceApplication's memory / runtime hooksLinux kernel (via eBPF)
Language dependencyHigh (requires specific agent for each language)None (operates on kernel's view of process)
Code modificationRequiredNot required (observes process from outside)
OutcomeDeep insight for known languagesGreat insight for any workload on Linux (C++, Rust, etc.)
+ +## 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 + + +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. + + + +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: + + + + + + + + + + + + + + + + + + + + + +
Application metric sourceNetwork metric sourceConfiguration
APM language agenteBPF agent (network metrics only mode)Two agents
eBPF agent (eAPM)eBPF agent (same agent)Single agent
+ +### 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] + + + Learn how to set up the New Relic eBPF agent for your Kubernetes cluster. + Learn how to set up the New Relic eBPF agent for your Linux host. + Learn how to troubleshoot issues with the New Relic eBPF agent. + diff --git a/src/content/docs/ebpf/k8s-installation.mdx b/src/content/docs/ebpf/k8s-installation.mdx index c3990800a11..3fc241381c8 100644 --- a/src/content/docs/ebpf/k8s-installation.mdx +++ b/src/content/docs/ebpf/k8s-installation.mdx @@ -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 @@ -11,20 +11,25 @@ tags: freshnessValidatedDate: never --- - -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. - 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 + + + + + +### 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. + -## Install the eBPF agent [#install] + + + +### Install the eBPF agent [#install] To install the eBPF agent: @@ -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**. + +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"]`. + + 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. @@ -59,8 +68,11 @@ To install the eBPF agent: kubectl get pods -n newrelic ``` + -## Access the eBPF data in New Relic [#access-data] + + +### 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). @@ -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. - - - - 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]`. + - * In Kubernetes, names are derived from the service name for example, `mysql-database-service`. - - + {/* 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 */} +## 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= --set cluster="" --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= --set cluster="" --namespace=newrelic --version=0.2.5 +``` + +Replace `` with your New Relic license key and `` 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: @@ -523,3 +534,26 @@ This section configures secure communication between the eBPF agent and client c + + + + + +## Uninstall the eBPF agent [#uninstall] + +To uninstall the eBPF agent from your Kubernetes cluster: + +```bash +helm uninstall nr-ebpf-agent -n newrelic +``` + + +This command will remove all eBPF agent components from your cluster. The namespace will remain unless you explicitly delete it. + + + + + Learn how to set up the New Relic eBPF agent for your Linux host. + Learn how to troubleshoot issues with the New Relic eBPF agent. + Learn about best practices for using the New Relic eBPF agent. + \ No newline at end of file diff --git a/src/content/docs/ebpf/linux-installation.mdx b/src/content/docs/ebpf/linux-installation.mdx index bd30fef2e1d..26ff42ef901 100644 --- a/src/content/docs/ebpf/linux-installation.mdx +++ b/src/content/docs/ebpf/linux-installation.mdx @@ -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 Linux hosts" +metaDescription: "Learn how to install and configure the New Relic eBPF agent for your Linux host with Debian package installation." tags: - New Relic integrations with eBPF - New Relic eBPF agent @@ -11,29 +11,25 @@ tags: freshnessValidatedDate: never --- - -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. - 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. -## Compatibility and requirements [#requirements] +## Install the New Relic eBPF agent + + + + +### Before you begin [#requirements] -* Linux kernel versions `5.4` and later. -* Root privileges -* Support `arm64` and `x86-64` architectures. -* A minimum of `2 GB` of RAM is required for host installations. -* Supports the following distributions: - * Ubuntu `20.04` and later - * Debian `11` and later - * CentOS Stream `9` and later - * RHEL `8` and later +You must meet the prerequisites outlined in the [eBPF compatibility and requirements](/docs/ebpf/requirements#linux) documentation for Linux hosts. + -## Install the eBPF agent [#install] + + +### Install the eBPF agent [#install] To install the eBPF agent: @@ -47,10 +43,9 @@ To install the eBPF agent: * **Create a new key**: If you don't have a user key, click **Create a new key** to create one. 6. On the Configure the host integration screen, enter the deployment name for host, then click **Continue**. -7. On the Install the agent screen, run the provided command in your terminal to install the eBPF agent. +7. 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 host. - + 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: @@ -72,7 +67,11 @@ To install the eBPF agent: -## Access the eBPF data in New Relic [#access-data] + + + + +### 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). @@ -87,35 +86,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. - - - - The eBPF agent automatically generates entity names differently depending on the environment: - - * 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]`. - - * In Kubernetes, these names are derived from the service name for example, `mysql-database-service`. - - Assigning custom name to applications: - - * You can assign a name of your choice to your application by setting the `NEW_RELIC_APP_NAME` environment variable for both docker containers and on-host applications. + - * The named application will appear in the New Relic UI suffixed with `-ebpf`. - - + {/* @@ -129,6 +102,20 @@ 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 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. + + +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: + +1. Go to **[one.newrelic.com](https://one.newrelic.com) > + Integration & Agents > eBPF Agent** +2. Follow the installation flow to get the updated command +3. Run the command on your host to upgrade the agent + ## Configuration parameters [#config-params] @@ -355,3 +342,23 @@ The `newrelic-ebpf-agent.conf` file contains the following configuration paramet + + + +## Uninstall the eBPF agent [#uninstall] + +To uninstall the eBPF agent from a Linux host, use your system's package management tools: + +```bash +sudo apt-get remove newrelic-ebpf-agent +``` + + +It is not necessary to stop the service before running the uninstall command. + + + + Learn how to set up the New Relic eBPF agent for your Kubernetes cluster. + Learn how to troubleshoot issues with the New Relic eBPF agent. + Learn about best practices for using the New Relic eBPF agent. + diff --git a/src/content/docs/ebpf/network-metrics.mdx b/src/content/docs/ebpf/network-metrics.mdx new file mode 100644 index 00000000000..a786faa764c --- /dev/null +++ b/src/content/docs/ebpf/network-metrics.mdx @@ -0,0 +1,76 @@ +--- +title: "eBPF network metrics" +metaDescription: "Learn how to configure New Relic eBPF network monitoring dashboard." +tags: + - Integrations + - eBPF integration + - eAPM + - eBPF Network monitoring + - extended Berkeley Packet Filter (eBPF) + - Linux host + - Kubernetes cluster +freshnessValidatedDate: never +--- + + + +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. + + + +The eBPF network monitoring 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. + +The network metrics has following tabs to monitor different aspects of network performance: + +* Errors: Displays DNS, TCP, and other network-related errors. +* Latency: Monitors key latencies like TCP handshakes, packet delivery, and the duration of short-lived connections. +* Packet loss: Tracks any packets dropped during transmission. It also contains information such as Kernel packet dropped, TCP connection timeouts, and packet retransmitted. +* TCP codes: Displays the status codes for TCP connections for both inbound and outbound traffic. +* Connections: Displays the inbound and outbound TCP connections, connection count, average connection duration, and max connection duration. + + +## Enroll to eBPF network monitoring [#enroll-pp] + +You can enroll to eBPF network monitoring from the **Preview & Trials** page: + +1. Go to **[one.newrelic.com > Administration](https://one.newrelic.com/admin-portal)**. +2. From the left nav, click **Preview & Trials**. +3. From the list of available preview features, click **eBPF network monitoring**. +4. Follow the on-screen instructions and accept the terms & conditions to complete the onboarding. Now, you can experience the new eBPF network monitoring capabilities from the APM. + + +## View the eBPF network monitoring data [#view-network-data] + +You can view the eBPF network monitoring data in the New Relic APM UI: + + +1. Go to **[one.newrelic.com](https://one.newrelic.com) > APM & Services**. +2. Select the desired eBPF entity. +3. In the Monitor section, click **Network Metrics**. + The network metrics displays. + + + + +The eBPF agent automatically generates entity names differently depending on the environment: + + * In hosts or Docker, these 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]`. + + * In Kubernetes, these names are derived from the service name for example, `mysql-database-service`. + +Assigning custom name to applications: + + * You can assign a name of your choice to your application by setting the `NEW_RELIC_APP_NAME` environment variable for both docker containers and on-host applications. + + * The named application will appear in the New Relic UI suffixed with `-ebpf`. + + + + + + Learn how to set up the New Relic eBPF agent for your Kubernetes cluster. + Learn how to set up the New Relic eBPF agent for your Linux host. + Learn how to troubleshoot issues with the New Relic eBPF agent. + \ No newline at end of file diff --git a/src/content/docs/ebpf/overview.mdx b/src/content/docs/ebpf/overview.mdx index 0c3d93adcb0..5dcf7c86c84 100644 --- a/src/content/docs/ebpf/overview.mdx +++ b/src/content/docs/ebpf/overview.mdx @@ -1,6 +1,6 @@ --- title: "New Relic eBPF observability" -metaDescription: "Learn how to integrate the New Relic eBPF agent to your Linux host and Kubernetes cluster." +metaDescription: "Learn how New Relic eBPF observability provides zero-code monitoring for your Linux hosts and Kubernetes clusters with kernel-level visibility." tags: - Integrations - eBPF integration @@ -10,13 +10,8 @@ tags: freshnessValidatedDate: never --- - -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. - -New Relic eBPF observability helps you to monitor modern and complex networks and environments by providing a new layer of visibility. +{/* New Relic eBPF observability helps you to monitor modern and complex networks and environments by providing a new layer of visibility. ## What value does the eBPF agent provide? [#value] @@ -30,20 +25,12 @@ New Relic eBPF observability provides unified, zero-code visibility across Kuber /> -## Use cases [#use-cases] - -This solution addresses critical challenges for platform engineers: - -* **Faster troubleshooting:** Correlate application telemetry with infrastructure and network insights. This enables rapid diagnosis of performance issues, especially those that originate in the underlying system. - -* **Automatic discovery:** Get automated observability with zero instrumentation. The eBPF agent continuously identifies and maps all running services and their dependencies, providing a real-time architectural view of new or unknown workloads without requiring prior knowledge of the application's language. -* **Unified monitoring:** Monitor applications written in any language across diverse environments. This gives you consistent visibility and service-level performance analysis directly within the New Relic user interface. ## Impact [#impact] -You can achieve deeper observability and resolve issues more quickly with minimal resource overhead, ensuring that monitoring does not impact application performance. The agent provides unique kernel-level and network details for a comprehensive understanding of system dynamics. +You can achieve deeper observability and resolve issues more quickly with minimal resource overhead, ensuring that monitoring does not impact application performance. The agent provides unique kernel-level and network details for a comprehensive understanding of system dynamics. */} {/* Monitoring modern applications is challenging because they often run on complex and mixed infrastructure, from Kubernetes clusters to traditional Linux hosts such as, virtual machines and cloud instances. As you scale these environments, it becomes more difficult to gain visibility into performance without significant manual configuration. An engineer needs to know what applications are running in their cluster and which ones are causing performance degradation. Sometimes, application performance suffers due to issues in the underlying infrastructure that application owners cannot resolve with application-level tools alone. @@ -102,11 +89,126 @@ The New Relic eBPF agent has two modes: */} +Monitoring modern applications is challenging because they often run on complex, mixed infrastructure, from Kubernetes clusters to traditional Linux hosts. To keep up with demands for faster troubleshooting, engineers need to bridge the gap between application performance (APM) and infrastructure monitoring, a task that is often slow and manual. + +The New Relic eBPF observability solution addresses these challenges. It provides a single, lightweight, language-agnostic agent that works on both hosts and Kubernetes. By leveraging eBPF technology, the agent gains deep, "outside-in" insights directly from the Linux kernel. + +This approach allows you to: + +* **Simplify Observability:** Use one agent to automatically discover and monitor all services across Kubernetes clusters and Linux hosts/containers, regardless of programming language. +* **Accelerate Troubleshooting:** Instantly correlate application behavior with underlying infrastructure and network performance data. +* **Gain Deep Insights Without Intrusion:** Get full visibility into new, legacy, or third-party workloads without changing any application code. + + +The unified eBPF agent delivers two powerful, complementary capabilities: + +* [eBPF-powered APM](#ebpf-apm) +* [eBPF network metrics](#ebpf-network-metrics) + + +## Use cases [#use-cases] + +This solution addresses critical challenges for platform engineers: + +* **Faster troubleshooting:** Correlate application telemetry with infrastructure and network insights. This enables rapid diagnosis of performance issues, especially those that originate in the underlying system. + +* **Automatic discovery:** Get automated observability with zero instrumentation. The eBPF agent continuously identifies and maps all running services and their dependencies, providing a real-time architectural view of new or unknown workloads without requiring prior knowledge of the application's language. + +* **Unified monitoring:** Monitor applications written in any language across diverse environments. This gives you consistent visibility and service-level performance analysis directly within the New Relic user interface. + + + +## eBPF-powered APM (eAPM) [#ebpf-apm] + + +The eBPF-powered APM (eAPM) is our standard for no-code, language-agnostic application monitoring. It automatically discovers all services running on your hosts or Kubernetes nodes and populates the New Relic APM UI with performance data. This capability is ideal for getting a complete inventory of all your services, including those you cannot instrument manually, such as unknown workloads or third-party applications. + +### Key features + +* **Continuous service discovery:** Automatically discovers and maps all running application services, providing a real-time view of your architecture. +* **Zero-code instrumentation:** Provides deep visibility into application performance (including MELT data) without modifying application code or deploying language-specific agents. +* **Broad environment support:** Offers comprehensive support for Linux hosts (various distros) and Kubernetes clusters, across both **x86 and ARM64** architectures. +* **Detailed transaction insights:** Supports segmented linking, allowing you to see multiple segments within a transaction for deeper APM visibility. + +### Use cases + +* **For platform engineers:** Get an immediate and complete inventory of all services running on your platform, even those you don't own or that were deployed without your knowledge. +* **For teams with opaque workloads:** Instantly monitor legacy applications, third-party binaries, or services written in languages where you can't (or don't want to) modify the code. +* **For full-environment coverage:** Complement your existing traditional APM instrumentation by using eAPM to cover all the services that are not manually instrumented, ensuring 100% visibility. + + + +## eBPF network metrics [#ebpf-network-metrics] + + +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. + + +The eBPF network metrics provides deep visibility into the network communication of your applications. It captures granular TCP, IP, and DNS telemetry directly from the kernel, solving a major source of application performance issues. This capability is complementary to APM (both eAPM and traditional APM) and works independently to give you a complete picture of your application's communication health, helping you definitively answer the question: "Is it the application or the network?" + +To view the network metrics, refer to [network-metrics](/docs/ebpf/network-metrics/) documentation. + +### Key features + +* **Application-context network data:** All network metrics are automatically correlated with the specific application, service, and process that initiated them, making troubleshooting easy. +* **Granular DNS monitoring:** Tracks DNS resolution failures and reports the associated Fully Qualified Domain Name (FQDN). +* **Detailed TCP connection analysis:** Measures connection health and latency, including: + * **Handshake:** 3-Way handshake latency and success/failure counts. + * **Connection state:** Connection duration, data transmit duration, and counts for SYN, ACK, FIN, and RST packets. + * **Errors:** Tracks abnormal connection closures. +* **Packet-level IP insights:** Identifies packet loss and network optimization opportunities by monitoring: + * Bytes sent & received + * Packet retransmitted / dropped + * Packet delivery latency + +### Use cases + +* **For DevOps and SREs:** Quickly diagnose network-related performance bottlenecks by correlating application slowdowns with TCP handshake latency or packet drops. +* **For platform engineers:** Monitor the health of inter-service communication across the entire cluster, identify network saturation, and optimize network configurations. +* **For developers:** Understand how your application interacts with the network and its dependencies, and identify external network issues that are impacting your application's performance. + + ## How you can set up the eBPF agent [#setup] -You can install the New Relic eBPF agent on your Linux host and 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. +You can set up the New Relic eBPF agent on your Linux host or Kubernetes cluster. + + + + + +Ensure that your environments meets our [compatibility and requirements](/docs/ebpf/requirements) for your environment. -To set up the eBPF agent, follow the instructions in the: +* [Linux requirements](/docs/ebpf/requirements#linux) +* [Kubernetes requirements](/docs/ebpf/requirements#k8s) + + + + + +Depending on your environment, follow the appropriate installation guide: * [Linux installation guide](/docs/ebpf/linux-installation/) -* [Kubernetes installation guide](/docs/ebpf/k8s-installation/) \ No newline at end of file +* [Kubernetes installation guide](/docs/ebpf/k8s-installation/) + + + + + +### Find your data in New Relic [#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). + + + + + +## Related articles [#related-articles] + + + Learn about New Relic eBPF agent compatibility requirements, supported databases, platforms, and querying capabilities. + Learn how to set up the New Relic eBPF agent for your Kubernetes cluster. + Learn how to set up the New Relic eBPF agent for your Linux host. + + diff --git a/src/content/docs/ebpf/requirements.mdx b/src/content/docs/ebpf/requirements.mdx new file mode 100644 index 00000000000..c07b57bf733 --- /dev/null +++ b/src/content/docs/ebpf/requirements.mdx @@ -0,0 +1,223 @@ +--- +title: "eBPF compatibility and requirements" +metaDescription: "Learn about New Relic eBPF agent compatibility requirements, supported databases, platforms, and querying capabilities." +tags: + - New Relic integrations with eBPF + - New Relic eBPF agent + - eBPF integration + - eAPM + - eBPF compatibility + - eBPF requirements +freshnessValidatedDate: never +--- + +This page provides comprehensive compatibility information for the New Relic eBPF agent, including supported databases, deployment requirements, and data querying capabilities that apply to all installation methods. + + + + For Kubernetes + For Linux + + + + + + +Ensure that all [Kubernetes integration compatibility and requirements](/docs/kubernetes-pixie/kubernetes-integration/get-started/kubernetes-integration-compatibility-requirements/) are met. + +### Kubernetes environments [#k8-environments] + +The following Kubernetes environments are supported: + +* Amazon Elastic Kubernetes Service (EKS) +* Google Kubernetes Engine (GKE) +* Azure Kubernetes Service (AKS) + +***QUESTION TO Dev: Are we only supporting these above environments? Are we supporting Docker or any other container runtimes?*** + +### Database support matrix [#database-support] + +The eBPF agent can monitor the following databases and their supported versions: + + + + + + + + + + + + + + + + + + + + + + + + + + +
DatabaseSupported Versions
MySQL`v5.6.51` and later
MongoDB`v3.6.23` and later
Redis`v3.2.12` and later
PostgreSQL`v9.6.24` and later
+ +### Network requirements [#network-requirements] + +All eBPF deployments require access to these endpoints: + +**URL allowlist:** + +* `otlp.nr-data.net:443` +* `otlp.eu01.nr-data.net:443` (Required only for EU region accounts) +* `https://downloads.newrelic.com` +* `https://nr-downloads-ohai-staging.s3.amazonaws.com` + +**Port allowlist:** + +* For internal communication enable the port 12345 and port 4317 +* For external communication enable the port 443 + +**Mount path requirements:** + +* Root filesystem (`/`) +* System filesystem (`/sys`) + + + + + + +### Linux distributions [#linux-distributions] + +* Linux kernel versions `5.4` and later +* `arm64` or `x86-64` architectures +* Root privileges (sudo access required for installation and operation) +* A minimum of `2 GB` of RAM +* Supports the following Linux distributions: + * Debian `11` and later + * Ubuntu `20.04` and later + * CentOS Stream `9` and later + * RHEL `8` and later + + +### Database support matrix [#database-support] + +The eBPF agent can monitor the following databases and their supported versions: + + + + + + + + + + + + + + + + + + + + + + + + + + +
DatabaseSupported Versions
MySQL`v5.6.51` and later
MongoDB`v3.6.23` and later
Redis`v3.2.12` and later
PostgreSQL`v9.6.24` and later
+ +### Network requirements [#network-requirements] + +All eBPF deployments require access to these endpoints: + +**URL allowlist:** + +* `otlp.nr-data.net:443` +* `otlp.eu01.nr-data.net:443` (Required only for EU region accounts) +* `https://downloads.newrelic.com` +* `https://nr-downloads-ohai-staging.s3.amazonaws.com` + +**Port allowlist:** + +* For internal communication enable the port 12345 and port 4317 +* For external communication enable the port 443 + +**Mount path requirements:** + +* Root filesystem (`/`) +* System filesystem (`/sys`) + + + + + + + + + +{/* ## Querying eBPF data [#querying-data] + +Once the eBPF agent is deployed, telemetry data flows to New Relic and can be queried using NRQL. Here are common query patterns: + +### Query spans + +Including full-body requests and trace data: + +```sql +FROM Span +SELECT * WHERE +deployment.name = '' LIMIT MAX +``` + +### Query metrics + +Including TCP stats and performance metrics: + +```sql +FROM Metric +SELECT * WHERE +deployment.name = '' LIMIT MAX +``` + + + Replace `` with the actual deployment name you configured during installation. + + +### Entity naming + +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]`. + +* **In Kubernetes**: Names are derived from the service name, for example, `mysql-database-service`. + +## Data access in New Relic [#data-access] + +eBPF data is accessible through multiple New Relic interfaces: + +1. **APM & Services UI**: Go to **[one.newrelic.com](https://one.newrelic.com) > APM & Services** and filter by `instrumentation.name = nr_ebpf` + +2. **NRQL queries**: Use the query examples above to explore your data + +3. **OpenTelemetry UI**: eBPF data integrates with New Relic's OpenTelemetry experience + +For more information on accessing your data, see [OpenTelemetry APM UI](/docs/opentelemetry/get-started/apm-monitoring/opentelemetry-apm-ui). */} + + +## Related documentation [#related-docs] + + + Learn how to install the eBPF agent on Kubernetes. + Learn how to install the eBPF agent on Linux hosts. + Learn how to troubleshoot eBPF agent issues. + \ No newline at end of file diff --git a/src/content/docs/ebpf/troubleshooting/file-descriptor-limit.mdx b/src/content/docs/ebpf/troubleshooting/file-descriptor-limit.mdx new file mode 100644 index 00000000000..617e732d03d --- /dev/null +++ b/src/content/docs/ebpf/troubleshooting/file-descriptor-limit.mdx @@ -0,0 +1,161 @@ +--- +title: 'File descriptor limit exceeded' +type: troubleshooting +tags: + - Integrations + - eBPF integration + - Performance + - Troubleshooting +metaDescription: How to resolve file descriptor limit issues with the eBPF agent. +freshnessValidatedDate: never +--- + +## Problem + +You see the following error message in your eBPF agent logs: + +``` +The number of used file descriptors (820) is above the threshold (819). This may cause issues with attaching uprobes. Consider increasing the process FD limit +``` + +This error indicates that the eBPF agent has reached the maximum number of file descriptors it's allowed to use, which can prevent it from properly monitoring your applications. + +## Solution + +You must increase the file descriptor limit for the eBPF agent service or pod. + +### For Linux hosts: + +Use the `systemd` override mechanism to set a higher limit for the agent service. + +1. Increase the file descriptor limit temporarily: + + ```bash + ulimit -n 4096 + ``` + +2. Run the following command to edit the change persistent at `/etc/security/limits.conf`: + + ```bash + sudo nano /etc/security/limits.conf + ``` + + Add the following lines: + + ``` + * soft nofile 4096 + * hard nofile 8192 + ``` + +3. Restart the eBPF agent: + + ```bash + sudo systemctl restart newrelic-ebpf-agent + ``` + +4. Verify the new limit: + + ```bash + # Check current limits + cat /proc/$(pgrep newrelic-ebpf-agent)/limits | grep "Max open files" + ``` + +### For Kubernetes: + +1. Edit your `values.yaml` file used for the Helm deployment: + + ```yaml + # values.yaml + agent: + resources: + limits: + memory: "2Gi" + # Add security context if needed + securityContext: + capabilities: + add: + - SYS_ADMIN + ``` + +2. Apply the changes: + + ```bash + helm upgrade nr-ebpf-agent newrelic/nr-ebpf-agent -n newrelic -f values.yaml + ``` + +3. Verify the pods restart and are in a Running state: + + ```bash + kubectl get pods -n newrelic -w + ``` + +### Alternative solutions + +If increasing resource limits is not feasible, you can reduce the agent's file descriptor usage by limiting the scope of what it monitors. + +1. Reduce monitoring scope by filtering out namespaces or services: + + * **For Linux hosts** (`/etc/newrelic-ebpf-agent/newrelic-ebpf-agent.conf`): + + ```bash + # Exclude specific processes or entities + DROP_DATA_FOR_ENTITY="process1,process2" + ``` + + * **For Kubernetes** (`values.yaml`): + + ```yaml + # Exclude namespaces or services + dropDataForNamespaces: ["kube-system", "monitoring"] + dropDataServiceNameRegex: "kube-dns|system-service" + ``` + +2. Disable specific protocol monitoring to reduce the number of probes: + + * **For Linux hosts:** + + ```bash + PROTOCOLS_MYSQL_ENABLED="false" + PROTOCOLS_MONGODB_ENABLED="false" + ``` + + * **For Kubernetes:** + + ```yaml + protocols: + mysql: + enabled: false + mongodb: + enabled: false + ``` + +### Verification + +1. Check that the error no longer appears in the agent logs: + + * **For Linux hosts:** + + ```bash + sudo journalctl -u newrelic-ebpf-agent -f + ``` + + * **For Kubernetes:** + + ```bash + kubectl logs -f -n newrelic + ``` + +2. Confirm the agent is functioning normally by looking for the startup message in the logs: + + ``` + [STEP-7] => Successfully started the eBPF Agent. + ``` + +3. Verify data is flowing to New Relic UI by filtering entities with `instrumentation.name = nr_ebpf`. + +### Additional notes + +- The file descriptor limit error is more common in environments with many running processes or services. +- Each monitored process/service requires file descriptors for eBPF probe attachment. +- The default system limit (often 1024) may be insufficient for large-scale deployments. +- Increasing the limit to 4096 is generally safe and sufficient for most use cases. \ No newline at end of file diff --git a/src/content/docs/ebpf/troubleshooting/no-ui-data.mdx b/src/content/docs/ebpf/troubleshooting/no-ui-data.mdx new file mode 100644 index 00000000000..a28aebccf2a --- /dev/null +++ b/src/content/docs/ebpf/troubleshooting/no-ui-data.mdx @@ -0,0 +1,103 @@ +--- +title: 'No data appears in the UI' +type: troubleshooting +tags: + - Integrations + - eBPF integration + - Troubleshooting +metaDescription: Troubleshooting steps if eBPF data does not appear in the New Relic UI. +freshnessValidatedDate: never +--- + +## Problem + +You have installed the New Relic eBPF agent, but you don't see any eBPF data in your New Relic UI, or you're missing specific metrics or spans for certain protocols. + +## Solution + +### If no eBPF data appears at all: + +1. **Check network connectivity**: Ensure that the OTLP (OpenTelemetry Protocol) endpoint is not blocked by any firewall or network configuration. Verify these URLs are accessible: + * `otlp.nr-data.net:443` + * `otlp.eu01.nr-data.net:443` (EU region only) + * `https://downloads.newrelic.com` + * `https://nr-downloads-ohai-staging.s3.amazonaws.com` + + + +Ensure ports 4317 and 443 are unblocked at multiple levels: + + * **Cluster level**: For Kubernetes deployments (e.g., AKS clusters), verify the cluster's network security groups allow outbound traffic on these ports + * **Infrastructure level**: Check that security software (e.g., Microsoft Defender, corporate firewalls) isn't blocking these ports at the infrastructure level + +Port blocking can occur at both levels simultaneously, causing connectivity issues even if one level is properly configured. + + + +2. **Verify agent installation**: Check that the eBPF agent services are running: + + **For Linux hosts:** + ```bash + sudo systemctl status newrelic-ebpf-agent + sudo systemctl status newrelic-ebpf-agent-client + ``` + + **For Kubernetes:** + ```bash + kubectl get pods -n newrelic + ``` + +3. **Check agent logs**: Look for errors in the agent logs. Successful installation should show: + ``` + [STEP-7] => Successfully started the eBPF Agent. + ``` + +4. **Use the correct filter**: In the New Relic UI, filter entities by `instrumentation.name = nr_ebpf` to see eBPF-monitored services. + +### If specific metrics or spans are missing: + +1. **Verify protocol configuration**: Check that metrics and spans are enabled for the specific protocol in your configuration file: + + **For Linux hosts** (`/etc/newrelic-ebpf-agent/newrelic-ebpf-agent.conf`): + ```bash + PROTOCOLS_HTTP_ENABLED="true" + PROTOCOLS_HTTP_SPANS_ENABLED="true" + PROTOCOLS_MYSQL_ENABLED="true" + # ... other protocols + ``` + + **For Kubernetes** (in your `values.yaml`): + ```yaml + protocols: + http: + enabled: true + spans: + enabled: true + mysql: + enabled: true + ``` + +2. **Restart the agent** after configuration changes: + + **For Linux hosts:** + ```bash + sudo systemctl restart newrelic-ebpf-agent + ``` + + **For Kubernetes:** + ```bash + helm upgrade nr-ebpf-agent newrelic/nr-ebpf-agent -n newrelic --reuse-values + ``` + +3. **Check data filtering settings**: Verify that your entity isn't being excluded by configuration parameters like `DROP_DATA_FOR_ENTITY` or `dropDataServiceNameRegex`. + +### Additional verification steps: + +1. **Filter entities by host**: Use the `host.name` tag in the New Relic UI to filter entities running on a specific host. + +2. **Check entity naming**: Entities are automatically named as follows: + * **Linux hosts**: `processName:workingDirectory:[port]` (e.g., `ruby:/path/to/app:[5678]`) + * **Docker**: `processName:containerName:[port]` (e.g., `java:my-container:[8080]`) + * **Kubernetes**: Based on Kubernetes service name (e.g., `mysql-database-service`) + +3. **Verify custom naming**: If using `NEW_RELIC_APP_NAME`, the entity will appear with `-ebpf` suffix. diff --git a/src/content/docs/ebpf/troubleshooting/troubleshoot-k8s.mdx b/src/content/docs/ebpf/troubleshooting/troubleshoot-k8s.mdx new file mode 100644 index 00000000000..c5deae469b5 --- /dev/null +++ b/src/content/docs/ebpf/troubleshooting/troubleshoot-k8s.mdx @@ -0,0 +1,230 @@ +--- +title: 'Troubleshoot eBPF on Kubernetes' +type: troubleshooting +tags: + - Integrations + - eBPF integration + - Kubernetes + - Troubleshooting +metaDescription: Troubleshooting steps for eBPF agent issues specific to Kubernetes environments. +freshnessValidatedDate: never +--- + +This guide provides solutions for common issues you might encounter with the eBPF agent in a Kubernetes environment. Find your problem in the list below for specific resolution steps. + +In this guide, you'll find solutions for: + +* [File descriptor limit exceeded](#descriptor-limit-exceeded) +* [Privilege and permission issues](#privilege-and-permission-issues) +* [Performance and resource issues](#performance-and-resource-issues) +* [Pod startup and connectivity issues](#pod-startup-and-connectivity-issues) +* [Kubernetes-specific configuration issues](#kubernetes-specific-configuration-issues) + + + + + + +### Problem + +You're experiencing issues with the eBPF agent in your Kubernetes environment, such as file descriptor limits, privilege errors, or performance problems. + +### Solution + +If you encounter file descriptor limit errors, see our dedicated [file descriptor limit troubleshooting guide](/docs/ebpf/troubleshooting/file-descriptor-limit) for detailed resolution steps. + + + + + +### Problem + +eBPF agent fails to start due to insufficient privileges. + +### Solution + +1. Verify that the eBPF agent DaemonSet has the necessary privileges. The Helm chart should automatically configure required permissions. + +2. Check pod security context in your deployment: + + ```bash + kubectl describe pod -n newrelic + ``` + +3. Ensure your cluster supports eBPF. Check kernel version on nodes: + + ```bash + kubectl get nodes -o wide + # Kernel version should be 5.4 or later + ``` + + + + + + +### Problem + +eBPF agent consuming excessive resources or causing performance degradation. + +### Solution: + +1. Monitor resource usage: + + ```bash + kubectl top pods -n newrelic + ``` + +2. Adjust memory limits in your Helm values: + + ```yaml + agent: + resources: + limits: + memory: "2Gi" # Increase if needed + requests: + memory: "512Mi" + ``` + +3. Configure data filtering to reduce load: + + ```yaml + dropDataForNamespaces: ["kube-system", "monitoring"] + dropDataServiceNameRegex: "kube-dns|otel-collector" + ``` + +4. Limit protocol monitoring if not all protocols are needed: + + ```yaml + protocols: + http: + enabled: true + mysql: + enabled: false # Disable if not needed + ``` + + + + + + +### Problem + +eBPF agent pods not starting or unable to send data. + +### Solution + +1. Check pod status: + + ```bash + kubectl get pods -n newrelic + kubectl describe pod -n newrelic + ``` + +2. Review pod logs: + + ```bash + kubectl logs -n newrelic + ``` + +3. Verify network connectivity: + + ```bash + # Test from within the cluster + kubectl run test-connectivity --image=busybox --rm -it --restart=Never -- \ + nslookup otlp.nr-data.net + ``` + + + +Ensure ports 4317 and 443 are unblocked at multiple levels: + + * **Cluster level**: For Kubernetes deployments (e.g., AKS clusters), verify the cluster's network security groups allow outbound traffic on these ports + * **Infrastructure level**: Check that security software (e.g., Microsoft Defender, corporate firewalls) isn't blocking these ports at the infrastructure level + +Port blocking can occur at both levels simultaneously, causing connectivity issues even if one level is properly configured. + + + + +4. Check service account and RBAC: + + ```bash + kubectl get serviceaccount -n newrelic + kubectl get clusterrole,clusterrolebinding -l app.kubernetes.io/name=nr-ebpf-agent + ``` + + + + + +### Problem + +Entity names not appearing correctly or data not attributed to correct services. + +### Solution + +* The eBPF agent uses Kubernetes `Service` objects to name entities. Ensure your applications have a corresponding service defined. + + ```yaml + apiVersion: v1 + kind: Service + metadata: + name: my-service # This becomes the entity name + spec: + selector: + app: my-app + ``` + +* If you are missing data, ensure the namespace is not being excluded in your `values.yaml`. + + ```yaml + # In values.yaml + dropDataForNamespaces: [] # Remove namespaces you want to monitor + ``` + +* In Kubernetes, entity names are derived from the Kubernetes service name for example, `mysql-database-service`. On hosts or in 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]`. + +### Verification steps + +1. Check for successful startup log: + + ```bash + kubectl logs -n newrelic | grep "STEP-7" + ``` + Should show: `[STEP-7] => Successfully started the eBPF Agent.` + +2. Verify data flow in New Relic: + - In the New Relic UI, look for entities with `instrumentation.name = nr_ebpf`. + - Confirm that the entity names match your Kubernetes service names. + +3. Test OTLP endpoint connectivity: + + ```bash + kubectl exec -it -n newrelic -- \ + curl -v https://otlp.nr-data.net:443 + ``` + + + + \ No newline at end of file diff --git a/src/content/docs/kubernetes-pixie/kubernetes-integration/installation/eapm.mdx b/src/content/docs/kubernetes-pixie/kubernetes-integration/installation/eapm.mdx deleted file mode 100644 index eb8e6d913bf..00000000000 --- a/src/content/docs/kubernetes-pixie/kubernetes-integration/installation/eapm.mdx +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: "New Relic eBPF integration" -tags: - - Integrations - - eBPF integration - - eAPM -metaDescription: "Learn how to integrate the New Relic eBPF agent to your Kubernetes cluster." -freshnessValidatedDate: never ---- - - - -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. - - -The New Relic eBPF agent uses the extended Berkeley Packet Filter (eBPF) technology to monitor your Kubernetes cluster into New Relic's platform. The eBPF agent offers a new method for monitoring Kubernetes services, allowing customers to monitor their services without the need for language-specific agents. The eBPF agent collects data directly from the kernel, providing valuable insights into the performance of services running on the Kubernetes cluster. - -The New Relic eBPF agent is installed on each node of the Kubernetes cluster. After installation, the eBPF agent: - -* Detects all services running on the Kubernetes cluster. -* Collect the necessary data from the kernel. -* Send the data to the New Relic platform. - -You can view the eBPF instrumentation data in the APM UI to provide performance insights for the services running on the Kubernetes cluster. - -This data is populate in the APM UI to provide the performance insights for the services running on the Kubernetes cluster. - -## Key features [#key-features] - -Features of the eBPF agent integration include: - -* **Zero-code instrumentation:** Simplifies the monitoring process by eliminating the need for manual code instrumentation, reducing deployment complexity, and maintenance overhead. -* **Comprehensive observability:** Enables detailed visibility into application and network performance, helping to quickly identify and resolve issues. -* **Low-resource overhead:** Operates efficiently with minimal impact on system resources, leveraging its position within the kernel. -* **Future security enhancements:** Lays the groundwork for advanced security features such as runtime threat detection and policy enforcement. - - -## Key differences between eBPF and APM [#key-differences] - -The eBPF integration is a new way to monitor Kubernetes services, offering a different approach to monitoring services compared to the traditional APM agent. The key differences between the eBPF and APM agents are: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FunctionalityeBPF agentAPM agent
Summary✅✅
Transaction✅✅
Database OPS✅✅
External Service❌✅
Distributed Tracing❌✅
Programming language agnostic✅❌
Custom Instrumentation❌✅
Auto-discover apps and services continuously✅❌
Deduplicate Data Ingestion from eBPF✅✅
Linux support✅✅
Windows support❌✅
TCP and DNS telemetry✅❌
Does not require additional container✅❌
AgentOne per NodeOne per App
Telemetry Data SourceeBPFAPM language agent
- -## Installation of eBPF agent [#installation] - -A New Relic eBPF agent is installed on each node of your cluster. You can install the eBPF agent on your existing Kubernetes cluster using one of the following methods: - -- [Guided installation](#guided-installation) -- [Manual installation](#manual-installation) - - -### Prerequisites [#prerequisites] - -* Ensure that your Linux kernel version is v4.14 or above. -* Ensure that all [Kubernetes integration compatibility and requirements](/docs/kubernetes-pixie/kubernetes-integration/get-started/kubernetes-integration-compatibility-requirements/) are met. - - -### Guided installation [#guided-installation] - -The guided installation method is the easiest way to install the eBPF agent on your Kubernetes cluster. It offers pre-built resources and configurations to simplify the installation process. - -**To install the eBPF agent:** - -1. Log in to your New Relic account. -2. Go to **left navigation pane > + Integration & Agents > Guided install > Kubernetes**. -2. Select the instrumentation method from one of the following displayed options: - - - **Guided**: For integration using New Relic CLI. - - **Helm**: For integration using New Relic Helm charts. - - **Manifest**: For integration using New Relic Manifests. - -3. Click **Continue**. -4. 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](/docs/apis/intro-apis/new-relic-api-keys/#user-key). - * **Create a new key**: If you don't have a user key, click **Create a new key** to create one. - -5. On the **Configure the Kubernetes integration** screen, enter the following information, then click **Continue**: - - 1. **Choose a Kubernetes cluster name:** Enter your Kubernetes cluster name. This name must be the same as your Kubernetes cluster name. If the cluster is already instrumented in New Relic, select the cluster from the drop-down list. - 2. **Namespace for the integration:** Enter the namespace for the integration. The default namespace is `newrelic`. - 3. **Configure the Kubernetes operation mode:** If you are using the Google Kubernetes Engine (GKE), enable the **Are you using a GKE Autopilot cluster?** option. - -6. On the **Scrape Prometheus data** screen, select the applicable Prometheus data you want to scrape, then click **Continue**. -7. *(Optional)* On the **Enable APM auto-instrumentation** screen, if required, **enable the Activate APM auto-attach**, and then click **Continue**. For more information, refer [APM auto-instrumentation](/docs/kubernetes-pixie/kubernetes-integration/installation/k8s-agent-operator/). -8. On the **Gather Log data** screen, select the applicable options to forward log data, then click **Continue**. -9. On the **Install the Kubernetes integration** screen, click **Copy to clipboard**, then paste it to your host terminal. -10. After the installation is completed, click **Continue**. -11. *(Optional)* If you have enabled the APM auto-instrumentation, the **Configure APM auto-instrumentation** screen displays. Set the APM auto-instrumentation parameters as required, then click **Continue**. -12. On the **Test the connection** screen, click **Test connection** to verify the installation. - - - - During the installation, the eBPF agent is installed on each node of your cluster. For example, if you have three nodes in a Kubernetes cluster, then one eBPF agent is installed on each node. No additional configuration is required for this. - - - - -### Manual Installation - -Add the New Relic eBPF Helm chart to your existing Kubernetes cluster. - -### Prerequisites: - -- Download the [`value.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-ebpf-agent/values.yaml) file. -- You must have a valid New Relic ingest key. For more information, refer to [New Relic Keys](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/). - -### To manually install the eBPF agent: - -1. Open the [`value.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-ebpf-agent/values.yaml) file in your code editor. -2. Enter your Kubernetes cluster name for the `cluster` attribute. This name must be the same as your Kubernetes cluster name. -3. Add the New Relic ingest key for the `licenseKey` attribute. -4. Save the `value.yaml` file in your Kubernetes cluster. -5. To add the New Relic Helm chart repository, run: - - ```sh - - helm repo add newrelic https://helm-charts.newrelic.com - - ``` - -6. To install the eBPF agent Helm chart, replace `your-custom-values.yaml` with the path to your `values.yaml` file, run: - - ```sh - - helm upgrade nr-ebpf-agent newrelic/nr-ebpf-agent -f your-custom-values.yaml -n newrelic --create-namespace --install - - ``` -7. *(Optional)* To view pod deployment status in real-time, run: - - ```sh - - kubectl get pods -n newrelic --watch - - ``` - - The eBPF Helm chart offers multiple configuration options. Review the [`value.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-ebpf-agent/values.yaml) file to tailor the installation to your needs. - - - - - -## Access the eBPF-powered APM UI [#eBPF-access] - -To access the eBPF-powered APM UI: - -1. Go to [https://one.newrelic.com](https://one.newrelic.com) > **APM & Services**. -2. In the search banner, set the search criteria as `instrumentation.name = nr_ebpf`: - A screenshot showing the eBPF search bar - After the search is completed, a list of entities is displayed. The entity name for each service matches the service name in the Kubernetes cluster. - - -### Find and use data [#ui-screen] - -The eBPF agent generates data to power the New Relic APM experience, eliminating the need for additional custom instrumentation in your codebase. - - -## How eBPF agent and APM works together [#ebpf-apm] - -eBPF and New Relic APM agents are designed to complement one another. For example, a customer can begin by deploying the eBPF agent on their cluster using the guided or manual installation process. This agent automatically detects and reports all services within the cluster, providing a streamlined approach without the need to select a specific language agent. All services are reported collectively and promptly. - -Following the initial deployment, customers can evaluate the auto-discovered services and decide which ones require the comprehensive monitoring features of the full APM solution, including distributed tracing. - -When a service is upgraded to full APM monitoring, the eBPF agent stops collecting telemetry data for that service to avoid duplicate charges. Additionally, please note that the service will now be represented as a new entity, distinct from the one previously reported by eBPF, which will no longer receive data. - - -## Pricing information - -Your use of the New Relic eBPF agent is billable during preview in accordance with your Order. The costs associated with this feature are determined by the following factors, as applicable to the pricing model associated with your account: - -* **Data Ingest:** Charges may be based on the volume of data ingested, measured in GB ingested. This includes all data collected by the eBPF agent and transmitted to the New Relic platform. -* **APM UI Usage:** Charges may be incurred based on the utilization of the APM User Interface, measured in Compute Capacity Units (CCU) for the Core Compute Product. - -For further details on pricing, please contact our sales team or refer to your Order. - - - - -New Relic does not recommend installing both eBPF and Pixie on the same cluster. Since they both use eBPF, running these tools simultaneously may lead to excessive resource consumption and potentially degrade your cluster's performance. - - - diff --git a/src/nav/ebpf.yml b/src/nav/ebpf.yml index 58bb84b8fd9..d4e42304290 100644 --- a/src/nav/ebpf.yml +++ b/src/nav/ebpf.yml @@ -5,12 +5,26 @@ pages: path: /docs/ebpf/overview - title: Installation and configuration pages: -# - title: Compatibility and requirements -# path: /docs/ebpf/requirements + - title: Compatibility and requirements + path: /docs/ebpf/requirements - title: Linux installation path: /docs/ebpf/linux-installation - title: Kubernetes installation path: /docs/ebpf/k8s-installation + - title: Capabilities + pages: + - title: Network metrics + path: /docs/ebpf/network-metrics + - title: Troubleshooting + pages: + - title: No data appears + path: /docs/ebpf/troubleshooting/no-ui-data + - title: Troubleshoot eBPF on Kubernetes + path: /docs/ebpf/troubleshooting/troubleshoot-k8s + - title: File descriptor limit exceeded + path: /docs/ebpf/troubleshooting/file-descriptor-limit + - title: Best practices + path: /docs/ebpf/best-practices # - title: Ui and data # pages: # - title: understand and use the UI diff --git a/src/nav/kubernetes-pixie.yml b/src/nav/kubernetes-pixie.yml index b3e560e06be..7054d8f3ebf 100644 --- a/src/nav/kubernetes-pixie.yml +++ b/src/nav/kubernetes-pixie.yml @@ -19,8 +19,6 @@ pages: path: /docs/kubernetes-pixie/kubernetes-integration/installation/reduce-ingest - title: Kubernetes APM auto-attach path: /docs/kubernetes-pixie/kubernetes-integration/installation/k8s-agent-operator - - title: Install the eAPM agent - path: /docs/kubernetes-pixie/kubernetes-integration/installation/eapm - title: Manage Kubernetes alerts pages: - title: Predefined alert policy