From 44ce854a258d0ec69ca35f332691d2f879b6abfc Mon Sep 17 00:00:00 2001 From: ChengJinbao Date: Mon, 19 Sep 2022 14:36:17 -0400 Subject: [PATCH] Prohibit usage of enum value name strings in OTLP/JSON (#2758) * 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. * Fix grammar Co-authored-by: Bogdan Drutu --- 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 c91d820..824aadc 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