From 10b025b7cf9711083c101b7024a89f938cf91c06 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 29 Aug 2022 13:30:48 -0400 Subject: [PATCH 1/2] Prohibit usage of enum value name strings in OTLP/JSON Resolves https://github.com/open-telemetry/opentelemetry-proto/issues/424 This change disallows using enum value names as strings in OTLP/JSON and requires to use enum integer values only. --- specification/protocol/otlp.md | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/specification/protocol/otlp.md b/specification/protocol/otlp.md index c91d820bec2..c8726c9838e 100644 --- a/specification/protocol/otlp.md +++ b/specification/protocol/otlp.md @@ -399,13 +399,25 @@ response headers when sending binary Protobuf encoded payload. JSON Protobuf encoded payloads use proto3 standard defined [JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json) -for mapping between Protobuf and JSON, with one deviation from that mapping: the -`trace_id` and `span_id` byte arrays are represented as -[case-insensitive hex-encoded strings](https://tools.ietf.org/html/rfc4648#section-8), -they are not base64-encoded like it is defined in the standard -[JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json). -The hex encoding is used for `trace_id` and `span_id` fields in all OTLP -Protobuf messages, e.g. the `Span`, `Link`, `LogRecord`, etc. messages. +for mapping between Protobuf and JSON, with the following deviations from that mapping: + +- The `trace_id` and `span_id` byte arrays are represented as + [case-insensitive hex-encoded strings](https://tools.ietf.org/html/rfc4648#section-8), + they are not base64-encoded like as it is defined in the standard + [Protobuf JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json). + The hex encoding is used for `trace_id` and `span_id` fields in all OTLP + Protobuf messages, e.g. the `Span`, `Link`, `LogRecord`, etc. messages. + For example the `trace_id` field in a Span can be represented like this: + { "trace_id": "5B8EFFF798038103D269B633813FC60C", ... } + +- Values of enum fields MUST be encoded as integer values. Unlike the standard + [Protobuf JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json) + which allows values of enum fields to be encoded as either integer values or as enum + name strings, only integer enum values are allowed in OTLP JSON Protobuf Encoding, + the enum name strings MUST NOT be used. + For example the `kind` field with a value of SPAN_KIND_SERVER in a Span can be + represented like this: + { "kind": 2, ... } Note that according to [Protobuf specs]( https://developers.google.com/protocol-buffers/docs/proto3#json) 64-bit integer From 5c22fd6d0fd6bfb880f72c3b60f0b1c2281efe84 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Tue, 30 Aug 2022 10:59:18 -0400 Subject: [PATCH 2/2] Fix grammar --- specification/protocol/otlp.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/protocol/otlp.md b/specification/protocol/otlp.md index c8726c9838e..824aadc5582 100644 --- a/specification/protocol/otlp.md +++ b/specification/protocol/otlp.md @@ -402,20 +402,20 @@ JSON Protobuf encoded payloads use proto3 standard defined for mapping between Protobuf and JSON, with the following deviations from that mapping: - The `trace_id` and `span_id` byte arrays are represented as - [case-insensitive hex-encoded strings](https://tools.ietf.org/html/rfc4648#section-8), + [case-insensitive hex-encoded strings](https://tools.ietf.org/html/rfc4648#section-8); they are not base64-encoded like as it is defined in the standard [Protobuf JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json). The hex encoding is used for `trace_id` and `span_id` fields in all OTLP Protobuf messages, e.g. the `Span`, `Link`, `LogRecord`, etc. messages. - For example the `trace_id` field in a Span can be represented like this: + For example, the `trace_id` field in a Span can be represented like this: { "trace_id": "5B8EFFF798038103D269B633813FC60C", ... } - Values of enum fields MUST be encoded as integer values. Unlike the standard - [Protobuf JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json) + [Protobuf JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json), which allows values of enum fields to be encoded as either integer values or as enum - name strings, only integer enum values are allowed in OTLP JSON Protobuf Encoding, + name strings, only integer enum values are allowed in OTLP JSON Protobuf Encoding; the enum name strings MUST NOT be used. - For example the `kind` field with a value of SPAN_KIND_SERVER in a Span can be + For example, the `kind` field with a value of SPAN_KIND_SERVER in a Span can be represented like this: { "kind": 2, ... }