diff --git a/CHANGELOG.md b/CHANGELOG.md index bc7e1c7853e..8d6f273e399 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ release. ### Profiles +- Document the profiles signal. + ([#4685](https://github.com/open-telemetry/opentelemetry-specification/pull/4685)) + ### Resource ### Entities diff --git a/specification/glossary.md b/specification/glossary.md index 2a5e33cde72..3dfdabfdf4f 100644 --- a/specification/glossary.md +++ b/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) @@ -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 samples (stacktraces with associated metadata) of +an OpenTelemetry instrumentation scope. + +### Profiling + +Profiling describes the process of collecting data that will be reported with +the profiles signal. diff --git a/specification/profiles/README.md b/specification/profiles/README.md index 1d08917ed31..b0dfa1d3142 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -4,4 +4,60 @@ path_base_for_github_subdir: to: profiles/README.md ---> -# Profiles +# OpenTelemetry Profiles + +
+Table of Contents + + + +- [Overview](#overview) +- [Known values](#known-values) + + + +
+ +## 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/) | diff --git a/specification/profiles/pprof.md b/specification/profiles/pprof.md new file mode 100644 index 00000000000..de90f34ce3b --- /dev/null +++ b/specification/profiles/pprof.md @@ -0,0 +1,19 @@ +# Pprof + +**Status**: [Development](../document-status.md) + + + +- [Compatibility](#compatibility) + + + +## 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.