Add examples to OTLP/JSON

[tigrannajaryan]

OTLP/JSON is a human readable format. It would be nice to have some example payloads in the OTLP specification to demonstrate what it can look like. Examples sometimes are very useful when you want to understand the structure of the payload.

See for example a user asking for it: open-telemetry/opentelemetry-specification#2773 (comment)

[abitrolly]

Zipkin also shows how it would be rendered in GUI https://zipkin.io/pages/data_model.html

[sebastien-rosset]

How are timestamps supposed to be serialized when exporting OpenTelemetry metrics in JSON format? Is it nanoseconds since epoch or RFC 3339? There seems to be conflicting guidelines in the spec:

1. OpenTelemetry file exporter provides examples where timestamps are serialized as the number of nanoseconds since epoch, e.g. "endTimeUnixNano":"1581452773000000789" - The file is https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/file-exporter.md
2. In the JSON protobuf encoding, there is a link to https://protobuf.dev/programming-guides/proto3/#json, which states timestamps should be encoded as RFC 3339, e.g., "1972-01-01T10:00:20.021Z"

Presumably the JSON protobuf encoding section is normative (hence RFC 3339), whereas the examples in the "file exporter" section are just examples that may not have been updated? Or maybe the intent was that somehow the timestamps for the file exporter in JSON format are supposed to use the number of nanoseconds since the epoch?

[tigrannajaryan]

How are timestamps supposed to be serialized when exporting OpenTelemetry metrics in JSON format? Is it nanoseconds since epoch or RFC 3339?

It is not RFC 3339. See the time_unix_nano field definition here:

  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
  // 1970.

There seems to be conflicting guidelines in the spec:

1. OpenTelemetry file exporter provides examples where timestamps are serialized as the number of nanoseconds since epoch, e.g. "endTimeUnixNano":"1581452773000000789" - The file is https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/file-exporter.md

The example is correct.

2. In the JSON protobuf encoding, there is a link to https://protobuf.dev/programming-guides/proto3/#json, which states timestamps should be encoded as RFC 3339, e.g., "1972-01-01T10:00:20.021Z"

This guidance is not applicable to OTLP. The timestamp fields in OTLP are fixed64. The guidance you are referring to is about Timestamp data type that is distinct from fixed64.

The applicable language in OTLP spec is the following:

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.

We can add clarification to the spec to make it clearer, I created an issue for that: #460

[joaopgrassi]

I have a bunch of metrics and logs examples in JSON, that I use to try things out, as it's easier to create arbitrary JSON OTLP. If you want I can try working on this :)

[tigrannajaryan]

I have a bunch of metrics and logs examples in JSON, that I use to try things out, as it's easier to create arbitrary JSON OTLP. If you want I can try working on this :)

It would be great to have some examples. Please feel free to submit a PR.

[tigrannajaryan]

I moved this issue to https://github.com/open-telemetry/opentelemetry-proto since that's where the OTLP spec is now.

[joaopgrassi]

I put up a PR for it #463.