From e06176daa63b1588072008bc1a7dcb2fad315393 Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 05:00:33 -0400 Subject: [PATCH 01/13] Update profiles specification README.md and pprof.md This update take into account the recent introduction of a profiles signal concepts page, removes duplicate information and adds more relevant documentation. --- specification/profiles/README.md | 102 +++++++++++++++++++++++-------- specification/profiles/pprof.md | 13 ++-- 2 files changed, 82 insertions(+), 33 deletions(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index 3405a8b2b96..7c2197d5233 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -6,13 +6,24 @@ path_base_for_github_subdir: # OpenTelemetry Profiles +**Status**: [Development](/docs/specs/otel/document-status/) + +> [!NOTE] +> +> The profiles signal is still experimental and under active development. +> Breaking changes may be introduced in future versions. +
Table of Contents - [Overview](#overview) +- [Design goals](#design-goals) +- [Data Model](#data-model) - [Known values](#known-values) +- [Specifications](#specifications) +- [References](#references) @@ -20,33 +31,56 @@ path_base_for_github_subdir: ## Overview -Profiles are emerging as the fourth essential signal of observability, alongside -logs, metrics, and traces. They offer unparalleled insights into system and -application behavior, often uncovering performance bottlenecks overlooked by -other signals. - -Profiles provide granular, time-based views of resource consumption and -code execution, encompassing: - -* **Application-level profiling**: Reveals how software functions consume CPU, -memory, and other resources, highlighting slow or inefficient code. - -* **System-level profiling**: Offers a holistic view of the infrastructure, -pinpointing issues in operating system calls, kernel operations, and I/O. - -This performance picture can lead to: - -* **Faster Root Cause Analysis**: Quickly identifies the exact cause of -performance degradation. -* **Proactive Optimization**: Identifies potential issues before user impact. -* **Improved Resource Utilization**: Optimizes infrastructure for cost savings -and efficiency. -* **Enhanced Developer Productivity**: Helps developers validate code performance -and prevent regressions. - -In essence, while logs, metrics, and traces show "what" and "how much/where" -profiles explain "why" and "how efficiently" making them indispensable in modern -observability. +A **profile** is a collection of stack traces with associated values +representing resource consumption, collected from a running program. Profiling +is the process of collecting such profiles, typically by sampling program state +at regular intervals. + +For a general introduction to OpenTelemetry profiling and how it complements other +observability signals, see [Profiles concepts](/docs/concepts/signals/profiles). + +## Design goals + +The profiles signal is designed with the following goals in mind: + +- **Low overhead**: Enable profiling agents to operate continuously in production + environments without materially impacting application performance. +- **Efficient representation**: Reduces volume of data stored and transmitted, + by using dictionary tables to deduplicate repeated information across samples. +- **Compatibility with existing formats**: The data model is a superset of + established profiling formats such as [pprof](https://github.com/google/pprof) + and in most cases supports lossless conversions to and from these formats. + If that's not possible (e.g. custom extensions), the `original_payload_format` + field can be used to transmit the original information for future lossless + export or reinterpretation. +- **Correlation with other signals**: Profiles MUST be linkable to logs, metrics + and traces through shared resource context and, where applicable, + direct trace/span references. This is the primary differentiator of OpenTelemetry + profiles compared to standalone profiling solutions. + +## Data model + +The OpenTelemetry profiles data model is defined [here](./data-model.md). +It builds on the [pprof protobuf format](https://github.com/google/pprof/tree/main/proto) +and extends it with: + +- **Resource and scope context**: Each batch of profiles is associated with a + [Resource](/docs/specs/otel/resource/) and an + [InstrumentationScope](/docs/specs/otel/common/instrumentation-scope/), + consistent with logs, metrics and traces. +- **Generalized dictionary**: Deduplicates not only strings but also other messages + that exhibit redundancy. +- **Generalized attributes**: Most messages can carry attributes following the + same conventions as other signals, augmented with Unit information (`KeyValueAndUnit`). +- **Span context references**: Samples MAY include a `Link` (span ID and trace ID), + enabling direct linking between a profile sample and the trace/span during + which it was captured. + +For details on the required attributes for `Mapping` messages and the custom +hashing scheme for build id generation, see [Mappings](./mappings.md). + +For more information on compatibility with [pprof](https://github.com/google/pprof), +see [pprof](./pprof.md). ## Known values @@ -61,3 +95,17 @@ tools, known values are utilized. | Profile field | Known values | | ------------- | ------------ | | original_payload_format | [pprof](https://github.com/google/pprof/tree/main/proto), [jfr](https://en.wikipedia.org/wiki/JDK_Flight_Recorder) or [linux_perf](https://perfwiki.github.io/) | + + +## Specifications + +* [Profiles Data Model](./data-model.md) +* [Profiles Mappings Attributes](./mappings.md) +* [Profiles Pprof Compatibility](./pprof.md) + +## References + +- [Profiles Concepts](/docs/concepts/signals/profiles) +- [Profiles Semantic Conventions](/docs/specs/semconv/general/profiles) +- [OTEP0212 OpenTelemetry Profiles Vision](../../oteps/profiles/0212-profiling-vision.md) +- [OTEP0239 OpenTelemetry Profiles Data Model](../../oteps/profiles/0239-profiles-data-model.md) diff --git a/specification/profiles/pprof.md b/specification/profiles/pprof.md index de90f34ce3b..6248bd4542e 100644 --- a/specification/profiles/pprof.md +++ b/specification/profiles/pprof.md @@ -10,10 +10,11 @@ ## Compatibility -Original [pprof](https://github.com/google/pprof/tree/main/proto) is forward -compatible with OpenTelemetry Profiles in a sense that it can be transformed into -OpenTelemetry Profiles and again into [pprof](https://github.com/google/pprof/tree/main/proto) -without data loss. +Original [pprof](https://github.com/google/pprof/tree/main/proto) is compatible +with OpenTelemetry Profiles in that it can be transformed into OpenTelemetry Profiles +and back again into [pprof](https://github.com/google/pprof/tree/main/proto) without +data loss (convertibility but not wire compatibility). + +To enable this compatibility through explicit conversion, OpenTelemetry provides a `pprof` [namespace](https://opentelemetry.io/docs/specs/semconv/general/profiles/#compatibility-with-pprof) +in [Semantic Conventions](https://opentelemetry.io/docs/specs/semconv). -For this compatibility OpenTelemetry also provides a `pprof` namespace in -Semantic Conventions. From 3173d782be0c92ebd07171a0af993566a7a5b52f Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 05:12:49 -0400 Subject: [PATCH 02/13] Update changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d9fe28b04b0..c5a90cece37 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,9 @@ release. ### Profiles +- Remove duplicate information from and extend Profiles documentation (README.md, pprof.md). + ([#4932](https://github.com/open-telemetry/opentelemetry-specification/pull/4932)) + ### Resource ### Entities From 9db6b9b4969f33e0cf6fad9f26aa9e599250f9dc Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 05:17:55 -0400 Subject: [PATCH 03/13] Minor stylistic update --- specification/profiles/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index 7c2197d5233..961144ceec5 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -96,7 +96,6 @@ tools, known values are utilized. | ------------- | ------------ | | original_payload_format | [pprof](https://github.com/google/pprof/tree/main/proto), [jfr](https://en.wikipedia.org/wiki/JDK_Flight_Recorder) or [linux_perf](https://perfwiki.github.io/) | - ## Specifications * [Profiles Data Model](./data-model.md) From a7bfa13dc8a22ba40c412d554b31ce301ce00b7f Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 05:59:06 -0400 Subject: [PATCH 04/13] Fix links --- specification/profiles/README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index 961144ceec5..b50cc59674a 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -6,7 +6,7 @@ path_base_for_github_subdir: # OpenTelemetry Profiles -**Status**: [Development](/docs/specs/otel/document-status/) +**Status**: [Development](../document-status.md) > [!NOTE] > @@ -37,7 +37,7 @@ is the process of collecting such profiles, typically by sampling program state at regular intervals. For a general introduction to OpenTelemetry profiling and how it complements other -observability signals, see [Profiles concepts](/docs/concepts/signals/profiles). +observability signals, see [Profiles concepts](https://opentelemetry.io/docs/concepts/signals/profiles/). ## Design goals @@ -65,8 +65,7 @@ It builds on the [pprof protobuf format](https://github.com/google/pprof/tree/ma and extends it with: - **Resource and scope context**: Each batch of profiles is associated with a - [Resource](/docs/specs/otel/resource/) and an - [InstrumentationScope](/docs/specs/otel/common/instrumentation-scope/), + [Resource](../resource/README.md) and an [InstrumentationScope](../common/instrumentation-scope.md), consistent with logs, metrics and traces. - **Generalized dictionary**: Deduplicates not only strings but also other messages that exhibit redundancy. @@ -104,7 +103,7 @@ tools, known values are utilized. ## References -- [Profiles Concepts](/docs/concepts/signals/profiles) -- [Profiles Semantic Conventions](/docs/specs/semconv/general/profiles) +- [Profiles Concepts](https://opentelemetry.io/docs/concepts/signals/profiles/) +- [Profiles Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/general/profiles/) - [OTEP0212 OpenTelemetry Profiles Vision](../../oteps/profiles/0212-profiling-vision.md) - [OTEP0239 OpenTelemetry Profiles Data Model](../../oteps/profiles/0239-profiles-data-model.md) From 6b4382edb14a9f507f63529a1a2d8f8a3bf9a4f7 Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 07:43:26 -0400 Subject: [PATCH 05/13] Update language in pprof.md --- specification/profiles/pprof.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/profiles/pprof.md b/specification/profiles/pprof.md index 6248bd4542e..ad4bf0ee779 100644 --- a/specification/profiles/pprof.md +++ b/specification/profiles/pprof.md @@ -15,6 +15,6 @@ with OpenTelemetry Profiles in that it can be transformed into OpenTelemetry Pro and back again into [pprof](https://github.com/google/pprof/tree/main/proto) without data loss (convertibility but not wire compatibility). -To enable this compatibility through explicit conversion, OpenTelemetry provides a `pprof` [namespace](https://opentelemetry.io/docs/specs/semconv/general/profiles/#compatibility-with-pprof) +To enable this compatibility through explicit conversion, OpenTelemetry provides pprof-specific [guidelines](https://opentelemetry.io/docs/specs/semconv/general/profiles/#compatibility-with-pprof) in [Semantic Conventions](https://opentelemetry.io/docs/specs/semconv). From fe13670edfc9a06fa901dd86084b5ac61d048292 Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 13:06:19 +0100 Subject: [PATCH 06/13] Update specification/profiles/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Felix Geisendörfer --- specification/profiles/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index b50cc59674a..3db14bc312e 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -106,4 +106,4 @@ tools, known values are utilized. - [Profiles Concepts](https://opentelemetry.io/docs/concepts/signals/profiles/) - [Profiles Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/general/profiles/) - [OTEP0212 OpenTelemetry Profiles Vision](../../oteps/profiles/0212-profiling-vision.md) -- [OTEP0239 OpenTelemetry Profiles Data Model](../../oteps/profiles/0239-profiles-data-model.md) +- [OTEP0239 OpenTelemetry Profiles Data Model](../../oteps/profiles/0239-profiles-data-model.md) (See [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/tree/main/opentelemetry/proto/profiles/) for the latest version of the data model) From 763e2a64c33ddd1e9d290652d2513ca95c398ac5 Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 13:07:24 +0100 Subject: [PATCH 07/13] Update specification/profiles/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Felix Geisendörfer --- specification/profiles/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index 3db14bc312e..e60f64dd567 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -55,8 +55,7 @@ The profiles signal is designed with the following goals in mind: export or reinterpretation. - **Correlation with other signals**: Profiles MUST be linkable to logs, metrics and traces through shared resource context and, where applicable, - direct trace/span references. This is the primary differentiator of OpenTelemetry - profiles compared to standalone profiling solutions. + direct trace/span references. ## Data model From ec245d1a24bd71958966b5332dc7cbcd507067c6 Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 11 Mar 2026 13:09:07 +0100 Subject: [PATCH 08/13] Update specification/profiles/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Felix Geisendörfer --- specification/profiles/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index e60f64dd567..4ca85135e6a 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -57,7 +57,7 @@ The profiles signal is designed with the following goals in mind: and traces through shared resource context and, where applicable, direct trace/span references. -## Data model +## Data Model The OpenTelemetry profiles data model is defined [here](./data-model.md). It builds on the [pprof protobuf format](https://github.com/google/pprof/tree/main/proto) From 73ace80f1c3c45409585fcf231cd7d492ab8ce41 Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Thu, 12 Mar 2026 04:34:13 -0400 Subject: [PATCH 09/13] Update language re: definition of a profile --- specification/profiles/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index 4ca85135e6a..dbd2c782f58 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -32,9 +32,9 @@ path_base_for_github_subdir: ## Overview A **profile** is a collection of stack traces with associated values -representing resource consumption, collected from a running program. Profiling -is the process of collecting such profiles, typically by sampling program state -at regular intervals. +representing resource consumption and code execution, collected from a +running program. Profiling is the process of collecting such profiles, +typically by sampling program state at regular intervals. For a general introduction to OpenTelemetry profiling and how it complements other observability signals, see [Profiles concepts](https://opentelemetry.io/docs/concepts/signals/profiles/). From f587891324e7637b039a3045f6b59a929c9302be Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Thu, 19 Mar 2026 08:20:49 -0400 Subject: [PATCH 10/13] Change status from Development to Alpha --- specification/profiles/README.md | 7 +------ specification/profiles/mappings.md | 2 +- specification/profiles/pprof.md | 2 +- 3 files changed, 3 insertions(+), 8 deletions(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index dbd2c782f58..df198536ea7 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -6,12 +6,7 @@ path_base_for_github_subdir: # OpenTelemetry Profiles -**Status**: [Development](../document-status.md) - -> [!NOTE] -> -> The profiles signal is still experimental and under active development. -> Breaking changes may be introduced in future versions. +**Status**: [Alpha](../document-status.md)
Table of Contents diff --git a/specification/profiles/mappings.md b/specification/profiles/mappings.md index c524fb3a7f4..893300e1bcd 100644 --- a/specification/profiles/mappings.md +++ b/specification/profiles/mappings.md @@ -1,6 +1,6 @@ # Mappings -**Status**: [Development](../document-status.md) +**Status**: [Alpha](../document-status.md) This document defines the required attributes of [`Mapping`](../../oteps/profiles/0239-profiles-data-model.md#message-mapping) messages. diff --git a/specification/profiles/pprof.md b/specification/profiles/pprof.md index ad4bf0ee779..b39c9c36fd8 100644 --- a/specification/profiles/pprof.md +++ b/specification/profiles/pprof.md @@ -1,6 +1,6 @@ # Pprof -**Status**: [Development](../document-status.md) +**Status**: [Alpha](../document-status.md) From 5d7379a35f3b692382da5fc45db59d2d324a7751 Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Fri, 20 Mar 2026 13:01:30 -0400 Subject: [PATCH 11/13] Update 'data model' to 'data format' --- specification/profiles/README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index df198536ea7..3062e3f9067 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -15,7 +15,7 @@ path_base_for_github_subdir: - [Overview](#overview) - [Design goals](#design-goals) -- [Data Model](#data-model) +- [Data Format](#data-format) - [Known values](#known-values) - [Specifications](#specifications) - [References](#references) @@ -42,7 +42,7 @@ The profiles signal is designed with the following goals in mind: environments without materially impacting application performance. - **Efficient representation**: Reduces volume of data stored and transmitted, by using dictionary tables to deduplicate repeated information across samples. -- **Compatibility with existing formats**: The data model is a superset of +- **Compatibility with existing formats**: The data format is a superset of established profiling formats such as [pprof](https://github.com/google/pprof) and in most cases supports lossless conversions to and from these formats. If that's not possible (e.g. custom extensions), the `original_payload_format` @@ -52,9 +52,9 @@ The profiles signal is designed with the following goals in mind: and traces through shared resource context and, where applicable, direct trace/span references. -## Data Model +## Data Format -The OpenTelemetry profiles data model is defined [here](./data-model.md). +The OpenTelemetry profiles data format is [here](./data-format.md). It builds on the [pprof protobuf format](https://github.com/google/pprof/tree/main/proto) and extends it with: @@ -91,7 +91,7 @@ tools, known values are utilized. ## Specifications -* [Profiles Data Model](./data-model.md) +* [Profiles Data Format](./data-format.md) * [Profiles Mappings Attributes](./mappings.md) * [Profiles Pprof Compatibility](./pprof.md) @@ -100,4 +100,3 @@ tools, known values are utilized. - [Profiles Concepts](https://opentelemetry.io/docs/concepts/signals/profiles/) - [Profiles Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/general/profiles/) - [OTEP0212 OpenTelemetry Profiles Vision](../../oteps/profiles/0212-profiling-vision.md) -- [OTEP0239 OpenTelemetry Profiles Data Model](../../oteps/profiles/0239-profiles-data-model.md) (See [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/tree/main/opentelemetry/proto/profiles/) for the latest version of the data model) From 61113cedc023ed6acb3c1ea3ea89a17249f78c6e Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 1 Apr 2026 12:27:25 -0400 Subject: [PATCH 12/13] Update Changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a140cef5413..99fc5f5d5cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,9 @@ release. ### Profiles +- Remove duplicate information from and extend Profiles documentation (README.md, pprof.md). + ([#4932](https://github.com/open-telemetry/opentelemetry-specification/pull/4932)) + ### Resource - Clarify that a Resource describes the observed entity, not the component From 8cb76cb29a00c818deecf7a8def9dff92dd660ed Mon Sep 17 00:00:00 2001 From: Christos Kalkanis Date: Wed, 1 Apr 2026 12:28:37 -0400 Subject: [PATCH 13/13] Fix wording for ID --- specification/profiles/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/profiles/README.md b/specification/profiles/README.md index 3062e3f9067..2ecfd7d3d3f 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -70,7 +70,7 @@ and extends it with: which it was captured. For details on the required attributes for `Mapping` messages and the custom -hashing scheme for build id generation, see [Mappings](./mappings.md). +hashing scheme for build ID generation, see [Mappings](./mappings.md). For more information on compatibility with [pprof](https://github.com/google/pprof), see [pprof](./pprof.md).