From 018331f861d51665a8b8cea6d4b3bde649f7f44a Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 25 Sep 2025 11:19:42 +0200 Subject: [PATCH 1/8] edot/docs: add support for profiles Start to add documentation for the profiles support in EDOT. Signed-off-by: Florian Lehner --- .../1758791900-edot-profiling-docs.yaml | 32 ++++++++ .../config/configure-profiles-collection.md | 73 +++++++++++++++++++ internal/pkg/otel/samples/linux/profiles.yml | 15 ++++ .../otel/samples/linux/profiles_metrics.yml | 25 +++++++ 4 files changed, 145 insertions(+) create mode 100644 changelog/fragments/1758791900-edot-profiling-docs.yaml create mode 100644 docs/reference/edot-collector/config/configure-profiles-collection.md create mode 100644 internal/pkg/otel/samples/linux/profiles.yml create mode 100644 internal/pkg/otel/samples/linux/profiles_metrics.yml diff --git a/changelog/fragments/1758791900-edot-profiling-docs.yaml b/changelog/fragments/1758791900-edot-profiling-docs.yaml new file mode 100644 index 00000000000..adcaa18d382 --- /dev/null +++ b/changelog/fragments/1758791900-edot-profiling-docs.yaml @@ -0,0 +1,32 @@ +# Kind can be one of: +# - breaking-change: a change to previously-documented behavior +# - deprecation: functionality that is being removed in a later release +# - bug-fix: fixes a problem in a previous version +# - enhancement: extends functionality but does not break or fix existing behavior +# - feature: new functionality +# - known-issue: problems that we are aware of in a given version +# - security: impacts on the security of a product or a user’s deployment. +# - upgrade: important information for someone upgrading from a prior version +# - other: does not fit into any of the other categories +kind: feature + +# Change summary; a 80ish characters long description of the change. +summary: add documentation for the profiles support in EDOT + +# Long description; in case the summary is not enough to describe the change +# this field accommodate a description without length limits. +# NOTE: This field will be rendered only for breaking-change and known-issue kinds at the moment. +#description: + +# Affected component; usually one of "elastic-agent", "fleet-server", "filebeat", "metricbeat", "auditbeat", "all", etc. +component: "elastic-agent" + +# PR URL; optional; the PR number that added the changeset. +# If not present is automatically filled by the tooling finding the PR where this changelog fragment has been added. +# NOTE: the tooling supports backports, so it's able to fill the original PR number instead of the backport PR number. +# Please provide it if you are adding a fragment for a different PR. +#pr: https://github.com/owner/repo/1234 + +# Issue URL; optional; the GitHub issue related to this changeset (either closes or is part of). +# If not present is automatically filled by the tooling with the issue linked to the PR number. +#issue: https://github.com/owner/repo/1234 diff --git a/docs/reference/edot-collector/config/configure-profiles-collection.md b/docs/reference/edot-collector/config/configure-profiles-collection.md new file mode 100644 index 00000000000..285fd1ff68a --- /dev/null +++ b/docs/reference/edot-collector/config/configure-profiles-collection.md @@ -0,0 +1,73 @@ +--- +navigation_title: Profiles collection +description: Configure the EDOT Collector for profiles collection. +applies_to: + stack: preview 9.2 + serverless: + observability: + product: + edot_collector: preview +products: + - id: observability + - id: edot-collector +--- + +# Profiles support in EDOT + +Profiles represent the fourth pillar of observability, complementing logs, traces, and metrics. + +The Elastic Distributions of OpenTelemetry (EDOT) Collector includes a profiling receiver, which offers an eBPF-based, system-wide profiler. + +Deploying the EDOT Collector with a profiling receiver in Kubernetes should be done as a DaemonSet. This ensures comprehensive, node-level profiling across the entire complete cluster, providing consistent data collection, resilience, scalability, and simplified management. This approach is recommended for optimal performance and complete observability. + +::{note} +OpenTelemetry profiles is not yet a stable feature. To use it, Elastic Distributions +of OpenTelemetry (EDOT) Collector need to be started with the additional argument `--feature-gates=service.profilesSupport`. +:: + +## Full profiles collection + +For full profiles collection and reporting use the following configuration. + +::{note} +Please follow the steps in Kibana to [`set up Universal Profiling`] before applying the following configuration. +:: + +```yaml +receivers: + profiling: + SamplesPerSecond: 19 + +service: + pipelines: + profiles: + receivers: [ profiling ] + exporters: [ elasticsearch ] +``` + +## Generate metrics from profiles + +The system can be configured to generate and report metrics exclusively from profile information. This method contributes to a reduction in ingest traffic and storage costs. + +```yaml +connectors: + profilingmetrics: + by_frame: true + by_frametype: true + by_classification: true + +receivers: + profiling: + SamplesPerSecond: 19 + +service: + pipelines: + profiles: + receivers: [ profiling ] + exporters: [ profilingmetrics ] + metrics: + receivers: [ profilingmetrics ] + exporters: [ elasticsearch ] +``` + +[`set up Universal Profiling`]: https://www.elastic.co/docs/solutions/observability/infra-and-hosts/get-started-with-universal-profiling#profiling-configure-data-ingestion \ No newline at end of file diff --git a/internal/pkg/otel/samples/linux/profiles.yml b/internal/pkg/otel/samples/linux/profiles.yml new file mode 100644 index 00000000000..61da247f8e1 --- /dev/null +++ b/internal/pkg/otel/samples/linux/profiles.yml @@ -0,0 +1,15 @@ +receivers: + profiling: + SamplesPerSecond: 19 +exporters: + elasticsearch: + endpoints: [ "${env:ELASTIC_ENDPOINT}" ] + api_key: ${env:ELASTIC_API_KEY} + mapping: + mode: otel + +service: + pipelines: + profiles: + receivers: [ profiling ] + exporters: [ elasticsearch ] \ No newline at end of file diff --git a/internal/pkg/otel/samples/linux/profiles_metrics.yml b/internal/pkg/otel/samples/linux/profiles_metrics.yml new file mode 100644 index 00000000000..be01ec3bda6 --- /dev/null +++ b/internal/pkg/otel/samples/linux/profiles_metrics.yml @@ -0,0 +1,25 @@ +receivers: + profiling: + SamplesPerSecond: 19 + +connectors: + profilingmetrics: + by_frametype: true + by_frame: true + by_classification: true + +exporters: + elasticsearch: + endpoints: [ "${env:ELASTIC_ENDPOINT}" ] + api_key: ${env:ELASTIC_API_KEY} + mapping: + mode: otel + +service: + pipelines: + profiles: + receivers: [ profiling ] + exporters: [ profilingmetrics ] + metrics: + receivers: [ profilingmetrics ] + exporters: [ elasticsearch ] From 297c36e75ba9394a8c6510cb74ab087b5b1007f7 Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 25 Sep 2025 11:32:38 +0200 Subject: [PATCH 2/8] fixup: new line at end of file Signed-off-by: Florian Lehner --- internal/pkg/otel/samples/linux/profiles.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/internal/pkg/otel/samples/linux/profiles.yml b/internal/pkg/otel/samples/linux/profiles.yml index 61da247f8e1..e5155eb77c3 100644 --- a/internal/pkg/otel/samples/linux/profiles.yml +++ b/internal/pkg/otel/samples/linux/profiles.yml @@ -12,4 +12,5 @@ service: pipelines: profiles: receivers: [ profiling ] - exporters: [ elasticsearch ] \ No newline at end of file + exporters: [ elasticsearch ] + From bde739619f379cf3ebe72ac2f244cce1f837ac7e Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 25 Sep 2025 13:49:25 +0200 Subject: [PATCH 3/8] Reorganize docs --- .../config/configure-logs-collection.md | 2 +- .../config/configure-metrics-collection.md | 2 +- .../config/configure-profiles-collection.md | 51 +++++++++++++------ docs/reference/edot-collector/toc.yml | 1 + 4 files changed, 38 insertions(+), 18 deletions(-) diff --git a/docs/reference/edot-collector/config/configure-logs-collection.md b/docs/reference/edot-collector/config/configure-logs-collection.md index e3f0a8a20ac..5a8d9f507db 100644 --- a/docs/reference/edot-collector/config/configure-logs-collection.md +++ b/docs/reference/edot-collector/config/configure-logs-collection.md @@ -1,5 +1,5 @@ --- -navigation_title: Configure Logs Collection +navigation_title: Logs collection description: Learn how to configure and customize logs collection through the Elastic Distribution of OpenTelemetry Collector. applies_to: stack: diff --git a/docs/reference/edot-collector/config/configure-metrics-collection.md b/docs/reference/edot-collector/config/configure-metrics-collection.md index 654d213ff34..5b1e1dc4463 100644 --- a/docs/reference/edot-collector/config/configure-metrics-collection.md +++ b/docs/reference/edot-collector/config/configure-metrics-collection.md @@ -1,5 +1,5 @@ --- -navigation_title: Configure Metrics Collection +navigation_title: Metrics collection description: Learn how to configure and customize metrics collection through the Elastic Distribution of OpenTelemetry Collector. applies_to: stack: diff --git a/docs/reference/edot-collector/config/configure-profiles-collection.md b/docs/reference/edot-collector/config/configure-profiles-collection.md index 285fd1ff68a..4f8e71f71ea 100644 --- a/docs/reference/edot-collector/config/configure-profiles-collection.md +++ b/docs/reference/edot-collector/config/configure-profiles-collection.md @@ -1,6 +1,6 @@ --- navigation_title: Profiles collection -description: Configure the EDOT Collector for profiles collection. +description: Learn how to configure and customize profiles collection through the Elastic Distribution of OpenTelemetry Collector. applies_to: stack: preview 9.2 serverless: @@ -12,26 +12,27 @@ products: - id: edot-collector --- -# Profiles support in EDOT +# Configure profiles collection -Profiles represent the fourth pillar of observability, complementing logs, traces, and metrics. +The {{edot}} (EDOT) Collector includes a profiling receiver, which offers an eBPF-based, system-wide profiler. -The Elastic Distributions of OpenTelemetry (EDOT) Collector includes a profiling receiver, which offers an eBPF-based, system-wide profiler. +To activate and configure profiling and send profiles to {{ecloud}} or {{es}}, follow these instructions. -Deploying the EDOT Collector with a profiling receiver in Kubernetes should be done as a DaemonSet. This ensures comprehensive, node-level profiling across the entire complete cluster, providing consistent data collection, resilience, scalability, and simplified management. This approach is recommended for optimal performance and complete observability. +:::{important} +OpenTelemetry profiling is still under active development. Refer to [The State of Profiling](https://opentelemetry.io/blog/2024/state-profiling/) blog post for more information. +::: -::{note} -OpenTelemetry profiles is not yet a stable feature. To use it, Elastic Distributions -of OpenTelemetry (EDOT) Collector need to be started with the additional argument `--feature-gates=service.profilesSupport`. -:: +## Turn on profiling -## Full profiles collection +Follow these steps to turn on profiles collection through the EDOT Collector. -For full profiles collection and reporting use the following configuration. +:::::{stepper} +::::{step} Set up Universal Profiling +Follow the steps to [`set up Universal Profiling`] before applying the following configuration. +:::: -::{note} -Please follow the steps in Kibana to [`set up Universal Profiling`] before applying the following configuration. -:: +::::{step} Full profiles collection +For full profiles collection and reporting, use this Collector configuration: ```yaml receivers: @@ -44,10 +45,24 @@ service: receivers: [ profiling ] exporters: [ elasticsearch ] ``` +:::: + +::::{step} Activate profiling in the Collector +To activate profiling in the EDOT Collector, start it using the additional argument `--feature-gates=service.profilesSupport`. + +For example: + +```sh +sudo ./otelcol --config otel.yml --feature-gates=service.profilesSupport +``` +:::: +::::: ## Generate metrics from profiles -The system can be configured to generate and report metrics exclusively from profile information. This method contributes to a reduction in ingest traffic and storage costs. +You can configure the components to generate and report metrics exclusively from profile information. This method contributes to a reduction in ingest traffic and storage costs. + +The following example generates profiling metrics by frame, frame type, and classification: ```yaml connectors: @@ -70,4 +85,8 @@ service: exporters: [ elasticsearch ] ``` -[`set up Universal Profiling`]: https://www.elastic.co/docs/solutions/observability/infra-and-hosts/get-started-with-universal-profiling#profiling-configure-data-ingestion \ No newline at end of file +## Kubernetes deployments + +In Kubernetes, deploy the EDOT Collector with a profiling receiver as a DaemonSet. This ensures comprehensive, node-level profiling across the entire complete cluster, providing consistent data collection, resilience, scalability, and simplified management. This approach is recommended for optimal performance and full observability. + +[`set up Universal Profiling`]: docs-content://solutions/observability/infra-and-hosts/get-started-with-universal-profiling.md#profiling-configure-data-ingestion \ No newline at end of file diff --git a/docs/reference/edot-collector/toc.yml b/docs/reference/edot-collector/toc.yml index dffce135c8e..3e15ba449de 100644 --- a/docs/reference/edot-collector/toc.yml +++ b/docs/reference/edot-collector/toc.yml @@ -10,6 +10,7 @@ toc: - file: config/configure-metrics-collection.md - file: config/tail-based-sampling.md - file: config/authentication-methods.md + - file: config/configure-profiles-collection.md - file: config/proxy.md - file: components.md children: From 7456ee5559fba17186a169305d9eb8394af04e09 Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 25 Sep 2025 14:07:42 +0200 Subject: [PATCH 4/8] drop link to UP Signed-off-by: Florian Lehner --- .../edot-collector/config/configure-profiles-collection.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/edot-collector/config/configure-profiles-collection.md b/docs/reference/edot-collector/config/configure-profiles-collection.md index 4f8e71f71ea..8f116f6664c 100644 --- a/docs/reference/edot-collector/config/configure-profiles-collection.md +++ b/docs/reference/edot-collector/config/configure-profiles-collection.md @@ -28,7 +28,9 @@ Follow these steps to turn on profiles collection through the EDOT Collector. :::::{stepper} ::::{step} Set up Universal Profiling -Follow the steps to [`set up Universal Profiling`] before applying the following configuration. +Universal Profiling must be set up once before profiles information can be ingested and visualized. + +To set up Universal Profiling, navigate to Observability in Kibana and then to Infrastructure > Universal Profiling. If it's not yet configured, click the "Set up Universal Profiling" button and follow the on-screen instructions. The setup dialog will not appear if Universal Profiling is already configured. :::: ::::{step} Full profiles collection @@ -88,5 +90,3 @@ service: ## Kubernetes deployments In Kubernetes, deploy the EDOT Collector with a profiling receiver as a DaemonSet. This ensures comprehensive, node-level profiling across the entire complete cluster, providing consistent data collection, resilience, scalability, and simplified management. This approach is recommended for optimal performance and full observability. - -[`set up Universal Profiling`]: docs-content://solutions/observability/infra-and-hosts/get-started-with-universal-profiling.md#profiling-configure-data-ingestion \ No newline at end of file From c2050766bb5c4221edb1f98a1c26364384b36037 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 25 Sep 2025 15:01:49 +0200 Subject: [PATCH 5/8] Update configure-profiles-collection.md --- .../config/configure-profiles-collection.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/reference/edot-collector/config/configure-profiles-collection.md b/docs/reference/edot-collector/config/configure-profiles-collection.md index 8f116f6664c..d4aea52ed72 100644 --- a/docs/reference/edot-collector/config/configure-profiles-collection.md +++ b/docs/reference/edot-collector/config/configure-profiles-collection.md @@ -28,9 +28,13 @@ Follow these steps to turn on profiles collection through the EDOT Collector. :::::{stepper} ::::{step} Set up Universal Profiling -Universal Profiling must be set up once before profiles information can be ingested and visualized. +Universal Profiling must be set up before profiles can be ingested and visualized. -To set up Universal Profiling, navigate to Observability in Kibana and then to Infrastructure > Universal Profiling. If it's not yet configured, click the "Set up Universal Profiling" button and follow the on-screen instructions. The setup dialog will not appear if Universal Profiling is already configured. +To set up Universal Profiling, go to **Observability** in Kibana and then to **Infrastructure** > **Universal Profiling**. If it's not yet configured, select **Set up Universal Profiling** and follow the instructions. + +:::{note} +The setup dialog doesn't appear if Universal Profiling is already configured. +::: :::: ::::{step} Full profiles collection From ad272d2febf62214d1efbb526b4a2adacdfd12e2 Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 25 Sep 2025 15:52:47 +0200 Subject: [PATCH 6/8] drop regular profiling Signed-off-by: Florian Lehner --- .../1758791900-edot-profiling-docs.yaml | 32 ------------------- .../config/configure-profiles-collection.md | 26 --------------- 2 files changed, 58 deletions(-) delete mode 100644 changelog/fragments/1758791900-edot-profiling-docs.yaml diff --git a/changelog/fragments/1758791900-edot-profiling-docs.yaml b/changelog/fragments/1758791900-edot-profiling-docs.yaml deleted file mode 100644 index adcaa18d382..00000000000 --- a/changelog/fragments/1758791900-edot-profiling-docs.yaml +++ /dev/null @@ -1,32 +0,0 @@ -# Kind can be one of: -# - breaking-change: a change to previously-documented behavior -# - deprecation: functionality that is being removed in a later release -# - bug-fix: fixes a problem in a previous version -# - enhancement: extends functionality but does not break or fix existing behavior -# - feature: new functionality -# - known-issue: problems that we are aware of in a given version -# - security: impacts on the security of a product or a user’s deployment. -# - upgrade: important information for someone upgrading from a prior version -# - other: does not fit into any of the other categories -kind: feature - -# Change summary; a 80ish characters long description of the change. -summary: add documentation for the profiles support in EDOT - -# Long description; in case the summary is not enough to describe the change -# this field accommodate a description without length limits. -# NOTE: This field will be rendered only for breaking-change and known-issue kinds at the moment. -#description: - -# Affected component; usually one of "elastic-agent", "fleet-server", "filebeat", "metricbeat", "auditbeat", "all", etc. -component: "elastic-agent" - -# PR URL; optional; the PR number that added the changeset. -# If not present is automatically filled by the tooling finding the PR where this changelog fragment has been added. -# NOTE: the tooling supports backports, so it's able to fill the original PR number instead of the backport PR number. -# Please provide it if you are adding a fragment for a different PR. -#pr: https://github.com/owner/repo/1234 - -# Issue URL; optional; the GitHub issue related to this changeset (either closes or is part of). -# If not present is automatically filled by the tooling with the issue linked to the PR number. -#issue: https://github.com/owner/repo/1234 diff --git a/docs/reference/edot-collector/config/configure-profiles-collection.md b/docs/reference/edot-collector/config/configure-profiles-collection.md index d4aea52ed72..68ea0f88984 100644 --- a/docs/reference/edot-collector/config/configure-profiles-collection.md +++ b/docs/reference/edot-collector/config/configure-profiles-collection.md @@ -27,32 +27,6 @@ OpenTelemetry profiling is still under active development. Refer to [The State o Follow these steps to turn on profiles collection through the EDOT Collector. :::::{stepper} -::::{step} Set up Universal Profiling -Universal Profiling must be set up before profiles can be ingested and visualized. - -To set up Universal Profiling, go to **Observability** in Kibana and then to **Infrastructure** > **Universal Profiling**. If it's not yet configured, select **Set up Universal Profiling** and follow the instructions. - -:::{note} -The setup dialog doesn't appear if Universal Profiling is already configured. -::: -:::: - -::::{step} Full profiles collection -For full profiles collection and reporting, use this Collector configuration: - -```yaml -receivers: - profiling: - SamplesPerSecond: 19 - -service: - pipelines: - profiles: - receivers: [ profiling ] - exporters: [ elasticsearch ] -``` -:::: - ::::{step} Activate profiling in the Collector To activate profiling in the EDOT Collector, start it using the additional argument `--feature-gates=service.profilesSupport`. From 94fe07d15807d952649f4014376b809bc46cb5d8 Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 25 Sep 2025 15:53:23 +0200 Subject: [PATCH 7/8] drop second part Signed-off-by: Florian Lehner --- internal/pkg/otel/samples/linux/profiles.yml | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 internal/pkg/otel/samples/linux/profiles.yml diff --git a/internal/pkg/otel/samples/linux/profiles.yml b/internal/pkg/otel/samples/linux/profiles.yml deleted file mode 100644 index e5155eb77c3..00000000000 --- a/internal/pkg/otel/samples/linux/profiles.yml +++ /dev/null @@ -1,16 +0,0 @@ -receivers: - profiling: - SamplesPerSecond: 19 -exporters: - elasticsearch: - endpoints: [ "${env:ELASTIC_ENDPOINT}" ] - api_key: ${env:ELASTIC_API_KEY} - mapping: - mode: otel - -service: - pipelines: - profiles: - receivers: [ profiling ] - exporters: [ elasticsearch ] - From 12246cf755993d530e1c87689724debcf8f3f70b Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Thu, 25 Sep 2025 18:03:53 +0200 Subject: [PATCH 8/8] Update docs/reference/edot-collector/config/configure-profiles-collection.md Co-authored-by: Christos Kalkanis --- .../edot-collector/config/configure-profiles-collection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/edot-collector/config/configure-profiles-collection.md b/docs/reference/edot-collector/config/configure-profiles-collection.md index 68ea0f88984..4dbd3c0d3bc 100644 --- a/docs/reference/edot-collector/config/configure-profiles-collection.md +++ b/docs/reference/edot-collector/config/configure-profiles-collection.md @@ -67,4 +67,4 @@ service: ## Kubernetes deployments -In Kubernetes, deploy the EDOT Collector with a profiling receiver as a DaemonSet. This ensures comprehensive, node-level profiling across the entire complete cluster, providing consistent data collection, resilience, scalability, and simplified management. This approach is recommended for optimal performance and full observability. +In Kubernetes, we suggest deploying the EDOT Collector with a profiling receiver as a DaemonSet. This ensures comprehensive, node-level profiling across the entire cluster, providing consistent data collection, resilience, scalability, and simplified management. This approach is recommended for optimal performance and full observability.