From 7bc571b7b0c40f0d6a84d99b84c5f09380089184 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 29 Aug 2022 13:15:15 -0400 Subject: [PATCH] Refactor OTLP/HTTP section Make Binary and JSON encodings their own sections. This makes the spec easier to understand and also makes adding further clarifications to JSON easier. There are no functional changes. OTLP protocol behavior remains exactly the same. This is purely editorial change. --- specification/protocol/otlp.md | 64 +++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 25 deletions(-) diff --git a/specification/protocol/otlp.md b/specification/protocol/otlp.md index 64afb223dc2..c91d820bec2 100644 --- a/specification/protocol/otlp.md +++ b/specification/protocol/otlp.md @@ -23,6 +23,8 @@ nodes such as collectors and telemetry backends. + [OTLP/gRPC Service and Protobuf Definitions](#otlpgrpc-service-and-protobuf-definitions) + [OTLP/gRPC Default Port](#otlpgrpc-default-port) * [OTLP/HTTP](#otlphttp) + + [Binary Protobuf Encoding](#binary-protobuf-encoding) + + [JSON Protobuf Encoding](#json-protobuf-encoding) + [OTLP/HTTP Request](#otlphttp-request) + [OTLP/HTTP Response](#otlphttp-response) - [Full Success](#full-success-1) @@ -370,18 +372,49 @@ The default network port for OTLP/gRPC is 4317. ### OTLP/HTTP -**Status**: Binary format is [Stable](../document-status.md), - JSON format is [Experimental](../document-status.md) - -OTLP/HTTP uses Protobuf payloads encoded either in binary format or in JSON -format. The Protobuf schema of the messages is the same for OTLP/HTTP and -OTLP/gRPC. +OTLP/HTTP uses Protobuf payloads encoded either in +[binary format](#binary-protobuf-encoding) or in [JSON format](#json-protobuf-encoding). +Regardless of the encoding the Protobuf schema of the messages is the same for +OTLP/HTTP and OTLP/gRPC as +[defined here](https://github.com/open-telemetry/opentelemetry-proto/tree/master/opentelemetry/proto). OTLP/HTTP uses HTTP POST requests to send telemetry data from clients to servers. Implementations MAY use HTTP/1.1 or HTTP/2 transports. Implementations that use HTTP/2 transport SHOULD fallback to HTTP/1.1 transport if HTTP/2 connection cannot be established. +#### Binary Protobuf Encoding + +**Status**: [Stable](../document-status.md) + +Binary Protobuf encoded payloads use proto3 +[encoding standard](https://developers.google.com/protocol-buffers/docs/encoding). + +The client and the server MUST set "Content-Type: application/x-protobuf" request and +response headers when sending binary Protobuf encoded payload. + +#### JSON Protobuf Encoding + +**Status**: [Experimental](../document-status.md) + +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. + +Note that according to [Protobuf specs]( +https://developers.google.com/protocol-buffers/docs/proto3#json) 64-bit integer +numbers in JSON-encoded payloads are encoded as decimal strings, and either +numbers or strings are accepted when decoding. + +The client and the server MUST set "Content-Type: application/json" request and +response headers when sending JSON Protobuf encoded payload. + #### OTLP/HTTP Request Telemetry data is sent via HTTP POST request. The body of the POST request is a @@ -399,10 +432,6 @@ the request body is a Protobuf-encoded `ExportMetricsServiceRequest` message. The default URL path for requests that carry log data is `/v1/logs` and the request body is a Protobuf-encoded `ExportLogsServiceRequest` message. -The client MUST set "Content-Type: application/x-protobuf" request header when -sending binary-encoded Protobuf or "Content-Type: application/json" request -header when sending JSON encoded Protobuf payload. - The client MAY gzip the content and in that case MUST include "Content-Encoding: gzip" request header. The client MAY include "Accept-Encoding: gzip" request header if it can receive gzip-encoded responses. @@ -410,21 +439,6 @@ The client MAY gzip the content and in that case MUST include Non-default URL paths for requests MAY be configured on the client and server sides. -JSON-encoded Protobuf 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. - -Note that according to [Protobuf specs]( -https://developers.google.com/protocol-buffers/docs/proto3#json) 64-bit integer -numbers in JSON-encoded payloads are encoded as decimal strings, and either -numbers or strings are accepted when decoding. - #### OTLP/HTTP Response The response body MUST be the appropriate serialized Protobuf message (see below for