From 97b478cbf8748851bfabce5fd2cd644435a31f3a Mon Sep 17 00:00:00 2001
From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
Date: Tue, 8 Nov 2022 16:11:53 -0500
Subject: [PATCH] Prepare for declaring OTLP/JSON Stable (#435)
This adds guarantees that are necessary for OTLP/JSON wire representation
stability.
This does not yet declare OTLP/JSON. It will be a separate PR once we are
certain nothing else is needed.
---
README.md | 40 ++++++++++++++++++++--------------------
1 file changed, 20 insertions(+), 20 deletions(-)
diff --git a/README.md b/README.md
index 27987728c..a4ab9906c 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,10 @@ The compiled files are published to central repositories (Maven, ...) from OpenT
See [contribution guidelines](CONTRIBUTING.md) if you would like to make any changes.
+## OTLP/JSON
+
+See additional requirements for [OTLP/JSON wire representation here](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#json-protobuf-encoding).
+
## Generate gRPC Client Libraries
To generate the raw gRPC client libraries, use `make gen-${LANGUAGE}`. Currently supported languages are:
@@ -32,17 +36,17 @@ To generate the raw gRPC client libraries, use `make gen-${LANGUAGE}`. Currently
## Maturity Level
-Component | Maturity |
--------------------------------------|----------|
-**Binary Protobuf Encoding** | |
-common/* | Stable |
-metrics/\*
collector/metrics/* | Stable |
-resource/* | Stable |
-trace/trace.proto
collector/trace/* | Stable |
-trace/trace_config.proto | Alpha |
-logs/\*
collector/logs/* | Stable |
-**JSON encoding** | |
-All messages | Alpha |
+Component | Maturity |
+-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+**Binary Protobuf Encoding** | |
+common/* | Stable |
+metrics/\*
collector/metrics/* | Stable |
+resource/* | Stable |
+trace/trace.proto
collector/trace/* | Stable |
+trace/trace_config.proto | Alpha |
+logs/\*
collector/logs/* | Stable |
+**JSON encoding** | |
+All messages | [Alpha](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.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).
@@ -51,8 +55,7 @@ for definition of maturity levels).
Components marked `Stable` provide the following guarantees:
-- Field types will not change.
-- Field numbers will not change.
+- Field types, numbers and names will not change.
- Numbers assigned to enum choices will not change.
- Service names and service package names will not change.
- Service operation names, parameter and return types will not change.
@@ -60,23 +63,20 @@ Components marked `Stable` provide the following guarantees:
The following changes are allowed:
- Message names may change.
-- Field names may change.
- Enum names may change.
-- Enum choice names may change.
+- Enum choice names may change. This is allowed because enum choice names are not sent on
+ the wire.
- The location of messages and enums, i.e. whether they are declared at the top
lexical scope or nested inside another message may change.
- Package names may change.
- Directory structure, location and the name of the files may change.
-Note that none of the above allowed changes affects the binary wire representation.
+Note that none of the above allowed changes affects the binary wire representation or the
+JSON wire representation.
No guarantees are provided whatsoever about the stability of the code that
is generated from the .proto files by any particular code generator.
-In the future when OTLP/JSON is declared stable, several of the changes that
-are currently allowed will become disallowed since they are visible on the wire
-for JSON encoding.
-
## Experiments
In some cases we are trying to experiment with different features. In this case,