IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Universal Profiling Manage data storage »

› ›

Get started with Universal Profiling

edit

Get started with Universal Profiling

edit

On this page, you’ll learn how to configure and use Universal Profiling. This page covers:

Prerequisites to setting up Universal Profiling
Setting up Universal Profiling in your Elastic Cloud deployment
Installing the host-agent
Installing the Universal Profiling Agent integration

We would appreciate feedback on your experience with this product and any other profiling pain points you may have. See the send feedback section of the troubleshooting documentation for more information.

Prerequisites

edit

Before setting up Universal Profiling, make sure you meet the following requirements:

An Elastic Stack deployment on Elastic Cloud at version 8.7.0 or higher. Universal Profiling is currently only available on Elastic Cloud.
The workloads you’re profiling must be running on Linux machines with x86_64 or ARM64 CPUs.
The minimum supported kernel version is either 4.15 for x86_64 or 5.5 for ARM64 machines.
The Integrations Server must be enabled on your Elastic Cloud deployment.
Credentials (username and password) for the superuser Elasticsearch role (typically, the elastic user).

Interpreters

edit

Universal Profiling is a system-wide profiling solution with additional support for PHP, Python, Java (or any JVM language), Go, Rust, C/C++, Node.js/V8, Ruby, and Perl.

The minimum supported versions of each interpreter are:

JVM/JDK: 7
Python: 3.6
V8: 8.1.0
Perl: 5.28
PHP: 7.3
Ruby: 2.5

Deployment configuration example

edit

The following deployment configuration example was tested to support profiling data from a fleet of up to 500 hosts, each with 8 or 16 CPU cores, for a total of roughly 6000 cores:

Component	Size per zone (memory)	Zones
Elasticsearch	64 GB	2
Kibana	8 GB	1
Integrations Server	8 GB	1

Even if you’re profiling a smaller fleet, we recommend configuring at least two zones for Elasticsearch and 4 GB of memory each for the Integrations Server and Kibana.

Set up Universal Profiling on an Elastic Cloud deployment

edit

To set up Universal Profiling on your Elastic Cloud deployment, you need to configure data ingestion first.

Configure data ingestion

edit

After enabling Universal Profiling on your deployment for the first time, select any subheading under Universal Profiling in the navigation menu to open the following page:

Click Set up Universal Profiling to configure data ingestion.

To configure data ingestion, you need elevated privileges, typically the elastic user.

If you’re upgrading from a previous version with Universal Profiling enabled, see the upgrade guide.

When upgrading, you must remove all existing profiling data. We still recommend upgrading as the latest version contains several improvements and new features.

Known issue when configuring data ingestion

edit

If your Elastic Cloud deployment originated from version 7.x or earlier and is currently running on version 8.9.0–8.9.2, you may encounter a problem while trying to enable Universal Profiling.

Specifically, clicking the Set up Universal Profiling button triggers an error message that reads Error while setting up Universal Profiling. Upgrade to version 8.10.0 or more recent to fix this issue.

If you previously enabled Universal Profiling in Elastic Cloud version 8.9.0, and you’re re-executing the setup, you may also encounter this error. In this scenario, you need to complete the following step in addition to upgrading to the most recent version.

Open Dev Tools from the navigation menu and execute the following command:

When running the following command, customizations of APM and Fleet configurations will be erased.

POST kbn:/internal/fleet/reset_preconfigured_agent_policies/policy-elastic-agent-on-cloud

Install the host-agent

edit

You have the following options when installing the host-agent:

Install the host-agent using the Elastic Agent

edit

To install the host-agent using the Elastic Agent and the Universal Profiling Agent integration, complete the following steps:

Copy the secret token and Universal Profiling Collector url from the Elastic Agent Integration
Click Manage Universal Profiling Agent in Fleet to complete the integration.
On the Integrations page, click Add Universal Profiling Agent.
In Universal Profiling Agent → Settings, add the information you copied from the Add profiling data page:
1. Add the Universal Profiling collector URL to the Universal Profiling collector endpoint field.
2. Add the secret token to the Authorization field.
Click Save and continue.

Install the host-agent in standalone mode

edit

The host-agent profiles your fleet. You need to install and configure it on every machine that you want to profile. The host-agent needs root / CAP_SYS_ADMIN privileges to run.

After clicking Set up Universal Profiling in the previous step, you’ll see the instructions for installing the host-agent. You can also find these instructions by clicking the Add data button in the top-right corner of the page.

The following is an example of the provided instructions for Kubernetes:

Host-agent configuration notes

edit

Consider the following when configuring your host-agent:

The instructions in Kibana work well for testing environments. For production environments, we recommend setting an immutable version.
The host-agent versioning scheme is not aligned with the Elastic Stack version scheme.
The OS packages downloaded from releases.prodfiler.com have a version in their file name.
You can find a list of container image versions in the Elastic container library repository.
For Kubernetes deployments, the Helm chart version is already used to configure the same container image, unless overwritten with the version parameter in the Helm values file.
For Elastic Stack version 8.8 or higher, use v3 host agents. For version 8.7, use v2. v3 host agents are incompatible with 8.7 Elastic Stack versions.

« Universal Profiling Manage data storage »