Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Prepare for declaring OTLP/JSON Stable #435

Merged
merged 1 commit into from
Nov 8, 2022
Merged

Prepare for declaring OTLP/JSON Stable #435

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,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:
Expand All @@ -24,17 +28,17 @@ To generate the raw gRPC client libraries, use `make gen-${LANGUAGE}`. Currently

## Maturity Level

Component | Maturity |
-------------------------------------|----------|
**Binary Protobuf Encoding** | |
common/* | Stable |
metrics/\*<br>collector/metrics/* | Stable |
resource/* | Stable |
trace/trace.proto<br>collector/trace/* | Stable |
trace/trace_config.proto | Alpha |
logs/\*<br>collector/logs/* | Stable |
**JSON encoding** | |
All messages | Alpha |
Component | Maturity |
-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
**Binary Protobuf Encoding** | |
common/* | Stable |
metrics/\*<br>collector/metrics/* | Stable |
resource/* | Stable |
trace/trace.proto<br>collector/trace/* | Stable |
trace/trace_config.proto | Alpha |
logs/\*<br>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).
Expand All @@ -43,32 +47,28 @@ 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.

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,
Expand Down