bytes / Byte (uint8_t) arrays support

[maxgolov]

Current spec / protocol allows the following types:

bool
int32_t
int64_t
uint32_t
uint64_t
double
string (UTF-8, no UTF-16)

and

array of above primitive types.

Proposal is to add support for '8-bit byte array' event properties for Traces and Logs:

Practical reasons

• existing / legacy telemetry flows could already allow support for byte arrays.

• 8-bit byte array or bin type is available in MsgPack protocol.

• same type known in protobuf as bytes

• Most IoT protocols usually operate on 8-bit byte arrays or octet streams, allowing fields be either uint8_t or array / sequence of uint8_t, or the entire payload be 8-bit / octet stream.

• UUID or GUID type is best represented on SDK API surface and on wire as 16-bytes rather than 36+-character string, resulting in at least x2 times better performance for native (C/C++) code, as well as more compact net-bytes on wire. Although it may be possible to represent it as array of int32_t - it'd be a bit unnatural to do it.

• although it may be possible to convert byte array to base64-encoded string representation, this results in an extra encoding/decoding in SDK, elevated memory and CPU pressure, as well as type information (such as it's a binary blob, not a string) - is inherently lost.

Is it possible to add an optional provision to the protocol, that Platform SDKs that may require bin or octet stream or 8-bit byte array - may implement it on API surface?

Use-cases

Examples of exporters that would benefit from having byte array in the protocol spec:

• ETW - Event Tracing for Windows supports both GUID (16-bytes) and other arbitrary Byte arrays.
• Other telemetry systems previously using byte arrays flow for more compact binary data representation.

Not having this type natively supported by OpenTelemetry would impede the adoption of OT API / SDK by customers currently relying on octet / binary streams in their data flows. A reference implementation can be provided based on Open Telemetry C++ SDK to illustrate the use-cases, as well as perf implications of not having native support for byte arrays in API/SDK/proto/specification.

[Oberon00]

I also think that byte array support could be useful. One can use Base64 or hex encoded strings instead, but it does come with a performance cost.

[maxgolov]

I would like to have conditional provisions for this type implemented in OpenTelemetry C++ SDK. Disabled by default. But still there. Have ability to experiment with it and enable it later on.

Practical reason: if we allow bytes support on API surface, then we can later on determine whether concrete exporter supports bytes or not. In those scenarios where exporter cannot handle byte arrays, the exporter itself may convert the byte array to base64-encoded string..

But if exporter supports byte arrays, e.g.

• MessagePack - supports byte arrays - Binary type
• ETW - Event Tracing for Windows - supports win:Binary

Then it can forward the binary blob using the most compact representation of it. This may become relevant for scenarios where app or service needs to emit a small memory dump, IoT memory dump, or maybe its own representation of encrypted or serialized data structure.

Example code how the value attribute could be defined in C++, where the need for binary data type is common:

using AttributeValue =
    nostd::variant<bool,
                   int32_t,
                   int64_t,
                   uint32_t,
                   uint64_t,
                   double,
                   nostd::string_view,
#ifdef HAVE_SPAN_BYTE
                   // TODO: 8-bit byte arrays / binary blobs are not part of OT spec yet!
                   // Ref: https://github.com/open-telemetry/opentelemetry-specification/issues/780
                   nostd::span<const uint8_t>,
#endif
                   nostd::span<const bool>,
                   nostd::span<const int32_t>,
                   nostd::span<const int64_t>,
                   nostd::span<const uint32_t>,
                   nostd::span<const uint64_t>,
                   nostd::span<const double>,
                   nostd::span<const nostd::string_view>>;

It is ironic that we have string_view today - which carries string type semantics. It is structured about the same, but carries string. And we have arrays of 32-bit and above... Okay. But no 8-bit byte arrays? :-/ Even Javascript technically has 8-bit byte arrays, as in Uint8Array.

[maxgolov]

@Oberon00 @bogdandrutu @jsuereth @pyohannes

One concern here - since we got this tagged after-ga : adding new type to C++ API surface is going to be ABI-breaking change. This will be significant hassle for us, in terms of backward- / forward- compat.

What I am proposing right now:

• allow C++ SDK implement the incoming array of uint8_t bytes on API surface
• for the current implementation of OTLP exporter - put bytes into array of ints (already supported)
• for exporters that may care about byte arrays - allow them sending bytes as bytes, in the most compact binary representation. That'd be the case for MsgPack, fluentd-forward protocol, ETW.

What do you guys think?

[tigrannajaryan]

I agree this can be useful for attributes and also for the Log Record Body.

A prior art exists too: binary is a supported data type in Jaeger: https://github.com/jaegertracing/jaeger-idl/blob/34396033ff11c60fced342ab2858ace278fedaa8/proto/api_v2/model.proto#L57 for Span, Log and Process.

This has come up a few times in the past and recently here.

[tigrannajaryan]

Byte arrays (binary data) is also useful for log files where we don't want to interpret / don't know the encoding. See this feature request: open-telemetry/opentelemetry-collector-contrib#3267

[maxgolov]

@tigrannajaryan - thank you for your work! We already have a rough-in implementation in C++ SDK.
@open-telemetry/cpp-approvers

This feature also potentially enables us to reuse some of the existing APIs, or at least existing typing system for a feature like small (reasonably) -sized blob upload, expressing these as byte buffers.

[maxgolov]

@tigrannajaryan - My understanding is we should be able to close this issue, since the protocol work for that has been complete?

[cwildman]

@tigrannajaryan can we add the bytes type to the list of primitive types supported in the spec here?

[tigrannajaryan]

@tigrannajaryan can we add the bytes type to the list of primitive types supported in the spec here?

bytes data type was added to logs data model only. The attributes in the spec apply to all signals.

We have 2 possibilities:

1. Add an exception to that common attributes page to tell bytes are supported for logs but not for traces and metrics. This is probably the easiest short-term.
2. Decide that bytes are also valid type for traces/metrics. This may be the right long-term approach.

[bogdandrutu]

Would be also useful to determine how to convert this to "string", should we use base64?

[austinlparker]

Per https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#standard-attribute, we are not planning on extending the standard attribute types.

Our suggestion would be to use the forthcoming Events API/Data Model as a way to emit this information.