Add documentation for Profiling

[christos68k]

What needs to be changed?

As we're moving towards stabilization of the Profiling signal, we need to add documentation. This is what currently exists (if I missed something, please add it here):

• Profiles specification
• General -> Profiles semantic conventions

The Profiles specification landing page is empty but contains a link to a specification for Profiles Mappings, where we clarify Build ID usage and present an algorithm for the custom hashing scheme we use.

The Profiles semantic conventions page introduces the profile.frame.type attribute.

I'm opening this issue (as we've previously discussed in the SIG) to help coordinate the documentation work.

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

[christos68k]

Not sure why the bug label was added, it seems I don't have permissions to remove it and add docs.

[theletterf]

Thanks, @christos68k! I'll soon follow up with a proposal.

[svrnm]

Great news, @christos68k !

I added this to the agenda for next Comms meeting, as we need to find out where in the Information Architecture we want to have this

[theletterf]

At a high level, I'm thinking about the following:

• Conceptual docs under Concepts / Signals, which are currently lacking: https://opentelemetry.io/docs/concepts/signals/
• Develop https://opentelemetry.io/docs/specs/otel/profiles/
• How-to instructions for the Profiling Agent, either in a section on its own or inside the Collector's reference, with instructions on how to use it in K8s and bare-metal setups.

I think a dedicated first level section could help raise visibility of the project and host guides that ties together signals (think of trace-profiles correlation, OBI <-> Agent, etc.)

Let's discuss in the SIG comms call.

[svrnm]

We disucssed this during the last Comms call, and I should have followed up here, but we more or less agreed on the same what @theletterf lined out. What I want to emphasize is that we should start with a concept page about profiling that gives us (@open-telemetry/docs-maintainers) a better understanding of the moving pieces of profiling and then we can also make an easier decision where other pieces land

@open-telemetry/profiling-approvers, we would need one or some of you to provide that draft, we can then work together to get it out there :-)

[florianl]

With open-telemetry/opentelemetry-specification#4685 I have started a first attempt.

[florianl]

Another one: #8122