[spec/profiles] initial commit

CHANGELOG.md

@@ -19,6 +19,9 @@ release.
 
 ### Profiles
 
+- Document the profiles signal.
+  ([#4685](https://github.com/open-telemetry/opentelemetry-specification/pull/4685))
+
 ### Resource
 
 ### Entities

specification/glossary.md

@@ -39,6 +39,9 @@ Some other fundamental terms are documented in the [overview document](overview.
   * [Structured Logs](#structured-logs)
   * [Flat File Logs](#flat-file-logs)
   * [Log Appender / Bridge](#log-appender--bridge)
+- [Profiles](#profiles)
+  * [Profile](#profile)
+  * [Profiling](#profiling)
 
 <!-- tocstop -->
 
@@ -68,7 +71,7 @@ The maintainer of an OpenTelemetry SDK Plugin, written against OpenTelemetry SDK
 ### Signals
 
 OpenTelemetry is structured around signals, or categories of telemetry.
-Metrics, logs, traces, and baggage are examples of signals.
+Metrics, logs, traces, profiles, and baggage are examples of signals.
 Each signal represents a coherent, stand-alone set of functionality.
 Each signal follows a separate lifecycle, defining its current stability level.
 
@@ -228,3 +231,17 @@ library into OpenTelemetry using the [Log API](./logs/api.md). The
 terms "log bridge" and "log appender" are used interchangeably, reflecting that
 these components bridge data into OpenTelemetry, but are often called appenders
 in the logging domain.
+
+## Profiles
+
+Profiles describes the OpenTelemetry signal.
+
+### Profile
+
+In the context of the profiles signal, profile holds one or more stacktraces of
+a OpenTelemetry instrumentation scope.
+
+### Profiling
+
+Profiling describes the process of collecting data that will be reported with
+the profiles signal.

specification/profiles/README.md

@@ -4,4 +4,60 @@ path_base_for_github_subdir:
   to: profiles/README.md
 --->
 
-# Profiles
+# OpenTelemetry Profiles
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Known values](#known-values)
+
+<!-- tocstop -->
+
+</details>
+
+## 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.
+
+## Known values
+
+[OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/)
+are vital for profiles to correlate with other OpenTelemetry signals, enabling
+unified analysis of traces, metrics, logs, and profiles for a holistic
+system understanding.
+
+To enhance the compatibility of OpenTelemetry Profiles with existing profiling
+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/) |

specification/profiles/pprof.md

@@ -0,0 +1,19 @@
+# Pprof
+
+**Status**: [Development](../document-status.md)
+
+<!-- toc -->
+
+- [Compatibility](#compatibility)
+
+<!-- tocstop -->
+
+## 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.
+
+For this compatibility OpenTelemetry also provides a `pprof` namespace in
+Semantic Conventions.