From 6550c725aa2b5588e50594ca1fa0f839718b8a59 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 29 Aug 2022 13:30:48 -0400 Subject: [PATCH] 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