From 21db76083783d83767ef27db7124d32b60a155ad Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 17 May 2024 10:38:16 -0400 Subject: [PATCH] Document compatibility requirements for profiles Profiles maintainers, please take a look at the pprof compatibility criteria added to CONTRIBUTING.md. --- CONTRIBUTING.md | 13 +++++++++++++ README.md | 24 +++++++++++++----------- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 426dafe3a..0b1a1eb4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,3 +12,16 @@ for general information about the project. After making any changes to .proto files make sure to generate all implementation by running `make gen-all`. + +## Profiles Compatibility Requirements + +The Otel profile format in +[profiles/v1experimental](opentelemetry/proto/profiles/v1experimental) +is derived from +[pprof](https://github.com/google/pprof/tree/main/proto) and is currently +in experimental state. We would like to continue maintaining compatibility with pprof. +All changes to profile proto should meet the following compatibility criteria: + +- Every valid pprof profile is also a valid Otel profile AND, +- Every Otel profile is a valid pprof profile, after any new fields introduced in + Otel profile are discarded. diff --git a/README.md b/README.md index b84446eec..8e836b94b 100644 --- a/README.md +++ b/README.md @@ -36,17 +36,19 @@ To generate the raw gRPC client libraries, use `make gen-${LANGUAGE}`. Currently 1.0.0 and newer releases from this repository may contain unstable (alpha or beta) components as indicated by the Maturity table below. -| Component | Binary Protobuf Maturity | JSON Maturity | -| --------- |--------------- | ------------- | -| common/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| resource/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| metrics/\*
collector/metrics/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| trace/\*
collector/trace/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| logs/\*
collector/logs/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| profiles/\*
collector/profiles/* | Experimental | [Experimental](docs/specification.md#json-protobuf-encoding) | - -(See [maturity-matrix.yaml](https://github.com/open-telemetry/community/blob/47813530864b9fe5a5146f466a58bd2bb94edc72/maturity-matrix.yaml#L57) -for definition of maturity levels). +| Component | Binary Protobuf Maturity | JSON Maturity | +| --------- |--------------------------|------------------------------------------------------------------| +| common/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| resource/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| metrics/\*
collector/metrics/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| trace/\*
collector/trace/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| logs/\*
collector/logs/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| profiles/\*
collector/profiles/* | Experimental ** | [Experimental](docs/specification.md#json-protobuf-encoding) ** | + +** Additional requirements for profiles are [listed here](CONTRIBUTING.md#profiles-compatibility-requirements). + +See [maturity-matrix.yaml](https://github.com/open-telemetry/community/blob/47813530864b9fe5a5146f466a58bd2bb94edc72/maturity-matrix.yaml#L57) +for definition of maturity levels. ## Stability Definition