Update profiles specification README.md and pprof.md by christos68k · Pull Request #4932 · open-telemetry/opentelemetry-specification

christos68k · 2026-03-11T09:10:18Z

This update take into account the recent introduction of a profiles signal concepts page, removes duplicate information and adds more relevant documentation.

There will be a follow-up PR to add the current data model page. Do NOT merge this PR until the follow-up is also reviewed and approved as it currently links to a page (./data-model.md) that does not exist.

CC: @theletterf @open-telemetry/profiling-maintainers @open-telemetry/profiling-approvers

Changes

Please provide a brief description of the changes here.

For non-trivial changes, follow the change proposal process.

Related issues #7874
CHANGELOG.md file updated for non-trivial changes
- For trivial changes, include [chore] in the PR title to skip the changelog check

This update take into account the recent introduction of a profiles signal concepts page, removes duplicate information and adds more relevant documentation.

christos68k · 2026-03-11T09:20:33Z

specification/profiles/README.md


 ## Overview

-Profiles are emerging as the fourth essential signal of observability, alongside


I previously moved this overview to the Profiles concepts page.

specification/profiles/README.md

florianl · 2026-03-11T10:59:15Z

specification/profiles/pprof.md

+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)


Update the link to the pprof namespace and not the copy of some of this namespace in the Profiles space.

Suggested change

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 a `pprof` [namespace](https://opentelemetry.io/docs/specs/semconv/registry/attributes/pprof/)

I'll update the wording here to remove the reference to 'namespace' and keep the existing link as I think it's more helpful (it contains additional explanatory text that gives more context and helps frame the attributes that follow).

EDIT: See 6b4382e

florianl · 2026-03-11T11:01:42Z

specification/profiles/README.md

+
+> [!NOTE]
+>
+> The profiles signal is still experimental and under active development.


We should rephrase this note to sound less concerning.

Suggested change

> The profiles signal is still experimental and under active development.

> The profiles signal is currently marked as Alpha under development.

This is the same preamble as the one I added in Profiles concepts (which already went live). Since the signal isn't yet Alpha, I think this is more accurate.

We can update this to Alpha shortly before or immediately after the announcement.

Agreed. It's not yet marked as alpha (see this PR).

But maybe we don't need this whole paragraph since the Status is already declared above. Other documents with status "Development" don't seem to have such a Notes section either.

Anyway, since it's already in the other doc, I'm also fine with keeping it for now.

We should probably gather ourselves a list of all places that need to be coherently updated on the Alpha day.

Added open-telemetry/sig-profiling#83

florianl · 2026-03-11T11:06:49Z

specification/profiles/README.md

+- **Generalized attributes**: Most messages can carry attributes following the
+  same conventions as other signals, augmented with Unit information (`KeyValueAndUnit`).


As the topic around KeyValueAndUnit is under discussion and there will be some change, we should not point it out here. To me, its an implementation detail rather than a key concept in the data model.
Also, I think it does not add more to the data model that is not yet covered by **Generalized dictionary**.

Suggested change

- **Generalized attributes**: Most messages can carry attributes following the

same conventions as other signals, augmented with Unit information (`KeyValueAndUnit`).

I think we absolutely need to mention this here for two main reasons:

This is a major differentiator from pprof

It doesn't follow existing OTel conventions so questions may arise

I think one job of the spec is to clarify such corner cases instead of hiding them. Moreover, this is not just an implementation detail but a core aspect of the data model, which I'll also try to explain in data-model.md.

felixge

Some nits, but LGTM overall.

specification/profiles/README.md

felixge · 2026-03-11T11:52:23Z

specification/profiles/README.md

+
+> [!NOTE]
+>
+> The profiles signal is still experimental and under active development.


Agreed. It's not yet marked as alpha (see this PR).

But maybe we don't need this whole paragraph since the Status is already declared above. Other documents with status "Development" don't seem to have such a Notes section either.

Anyway, since it's already in the other doc, I'm also fine with keeping it for now.

specification/profiles/README.md

Co-authored-by: Felix Geisendörfer <felix@felixge.de>

aalexand · 2026-03-12T02:27:35Z

specification/profiles/pprof.md

-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


Should we merge this pprof.md file into the README.md, as a section? It's not a lot of text, so it might be easier to just have the single README.md file.

Given that we want really good integration with pprof due to its importance, I was thinking we'd want to expand the pprof information at some point, once we have a better/clearer story to tell there regarding conversions, recommendations, maybe an example and so on.

In that way it's similar to mappings.md, but I have no strong opinion on this for now (maybe if we leave it as a separate page it'll act as a nudge for us to improve it). If you feel strongly that we should merge it into the README, LMK and I will update.

Good point about expanding this at some point and the separate file being a nudge. SG to keep it separate.

Update profiles specification README.md and pprof.md

e06176d

This update take into account the recent introduction of a profiles signal concepts page, removes duplicate information and adds more relevant documentation.

christos68k requested review from a team as code owners March 11, 2026 09:10

Update changelog

3173d78

christos68k mentioned this pull request Mar 11, 2026

Add documentation for Profiling open-telemetry/opentelemetry.io#7874

Open

3 tasks

Minor stylistic update

9db6b9b

christos68k commented Mar 11, 2026

View reviewed changes

christos68k added the spec:profiling Related to the specification/profiling directory label Mar 11, 2026

theletterf approved these changes Mar 11, 2026

View reviewed changes

Fix links

a7bfa13

florianl reviewed Mar 11, 2026

View reviewed changes

Update language in pprof.md

6b4382e

felixge approved these changes Mar 11, 2026

View reviewed changes

christos68k and others added 3 commits March 11, 2026 13:06

Update specification/profiles/README.md

fe13670

Co-authored-by: Felix Geisendörfer <felix@felixge.de>

Update specification/profiles/README.md

763e2a6

Co-authored-by: Felix Geisendörfer <felix@felixge.de>

Update specification/profiles/README.md

ec245d1

Co-authored-by: Felix Geisendörfer <felix@felixge.de>

aalexand reviewed Mar 12, 2026

View reviewed changes

Update language re: definition of a profile

73ace80

florianl approved these changes Mar 13, 2026

View reviewed changes


		## Overview

		Profiles are emerging as the fourth essential signal of observability, alongside

	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 a `pprof` [namespace](https://opentelemetry.io/docs/specs/semconv/registry/attributes/pprof/)

	> The profiles signal is still experimental and under active development.
	> The profiles signal is currently marked as Alpha under development.

		- Generalized attributes: Most messages can carry attributes following the
		same conventions as other signals, augmented with Unit information (`KeyValueAndUnit`).

Conversation

christos68k commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christos68k Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christos68k Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christos68k Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christos68k Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

christos68k commented Mar 11, 2026 •

edited

Loading

christos68k Mar 11, 2026 •

edited

Loading

christos68k Mar 11, 2026 •

edited

Loading

christos68k Mar 11, 2026 •

edited

Loading

christos68k Mar 12, 2026 •

edited

Loading