The OpenTelemetry Protocol (OTLP)

The OpenTelemetry specification includes an exchange protocol, OTLP, that defines how data is serialized, deserialized, and transported between networked services. The goal of this protocol is to specify a serialization schema that closely adheres to the data models and solves problems that exist with other telemetry protocols. It also aims to define how to generally implement a client that can serialize and send the data, and how to implement a server that can accept the serialized data and indicate success or failure in its response.

OTLP uses protocol buffers to serialize telemetry data and gRPC or HTTP for sending it. The protocol works in all nodes from your telemetry client to the observability platform that receives your data and any services, agents, collectors, and forwarders in between.

OTLP is relevant to the OpenTelemetry data specification because the spec doesn’t only define what the data for each signal looks like at a high level, but it also specifies what it looks like at the code level. Specifically, it defines the protocol buffer schemas you use to serialize your data and send it over the wire.

Here’s a snippet from the trace protocol buffer schema:

message Span {
 bytes trace_id = 1;
 bytes span_id = 2;
 string trace_state = 3;
 bytes parent_span_id = 4;
 string name = 5;
 SpanKind kind = 6;
 fixed64 start_time_unix_nano = 7;
 fixed64 end_time_unix_nano = 8;
 repeated opentelemetry.proto.common.v1.KeyValue attributes = 9;
 uint32 dropped_attributes_count = 10;
 repeated Event events = 11;
 uint32 dropped_events_count = 12;
 repeated Link links = 13;
 uint32 dropped_links_count = 14;
 Status status = 15;
}

This message represents a trace’s span. You may not recognize the first few fields, because you haven’t yet learned about how traces are implemented, but most of the other fields should look familiar:

• The fifth field on the message is the span’s name. As you learned previously, the span’s name is a string of characters that identifies the operation the span represents.
• The seventh and eighth fields are the start and end timestamps of the span, respectively. These are stored as eight-byte integers that represent the number of nanoseconds it has been since the UNIX epoch (January 1, 1970). It’s more efficient to send integers over the wire than it is to send formatted timestamp strings.
• The ninth field represents the span’s attributes as a collection—denoted by the “repeated” data type—of KeyValue elements.
• The eleventh field stores a collection of Event objects.

In the schema, the Event and other custom data types that are more complex than primitive ones have their own definitions. In this case, you have:

message Event {
 fixed64 time_unix_nano = 1;
 string name = 2;
 repeated opentelemetry.proto.common.v1.KeyValue attributes = 3;
 uint32 dropped_attributes_count = 4;
}

This should look mostly familiar to you as it matches almost one-to-one with the data model you learned in a previous lesson.

When you reference or work with the data specification, it’s important to keep in mind that OpenTelemetry is still an evolving product. Some of the data signals are stable, have long-term support, and are guaranteed to not have subsequent minor releases with backward-incompatible changes. Others, however, are experimental or are currently being tested where there is no such guarantee of stability. Check out the Maturity Level chart in the opentelemetry-proto repository to see how mature each schema is.

Awesome! You’ve learned all about the OpenTelemetry data specification, including:

• What signals are
• What the spec defines about each signal
• What the trace data model looks like
• What attributes are in the scope of OpenTelemetry
• What span events are
• How the spec defines the OTLP schemas according to the data models

The specification doesn’t stop with defining telemetry data, though. It also specifies an interface for interacting with that data.