OpenTelemetry Protobuf Definitions

This repository contains the Protocol Buffer definitions for OTLP (the primary OpenTelemetry data delivery protocol), and other Protocols that share its common types and release machinery.

See contribution guidelines if you would like to make any changes.

Protocols

OTLP

The primary OpenTelemetry data delivery protocol, used to export traces, metrics, logs, and profiles via gRPC and HTTP.

Specification: docs/specification.md
Proto files: everything under opentelemetry/proto/ except processcontext/

OTLP/JSON

See additional requirements for OTLP/JSON wire representation here.

Generate gRPC Client Libraries

To generate the raw gRPC client libraries, use make gen-${LANGUAGE}. Currently supported languages are:

cpp
csharp
go
java
objc
openapi (swagger)
php
python
ruby

Process Context Sharing

A non-OTLP protocol for sharing process-level resource attributes with external readers (e.g. the OpenTelemetry eBPF Profiler) via memory-mapped regions. Not exchanged via gRPC, HTTP, or the OpenTelemetry Collector.

Documentation: docs/process-context/process-context.md
Proto file: opentelemetry/proto/processcontext/v1development/process_context.proto
Design doc: OTEP 4719

Language Independent Interface Types

The proto files can be consumed as GIT submodules or copied and built directly in the consumer project.

OpenTelemetry language libraries may publish generated language bindings. Check the documentation of the language library you are using for more details.

Maturity Level

1.0.0 and newer releases from this repository may contain unstable (alpha or beta) components as indicated by the Maturity table below.

Protocol	Component	Binary Protobuf Maturity	JSON Maturity
OTLP	common/*	Stable	Stable
OTLP	resource/*	Stable	Stable
OTLP	metrics/* collector/metrics/*	Stable	Stable
OTLP	trace/* collector/trace/*	Stable	Stable
OTLP	logs/* collector/logs/*	Stable	Stable
OTLP	profiles/* collector/profiles/*	Development	Development
Process Context Sharing	processcontext/*	Development	N/A

(See Versioning and Stability for definition of maturity levels).

Stability Definition

Components marked Stable provide the following guarantees:

Field types, numbers and names will not change.
Service names and service package names will not change.
Service method names will not change. [from 1.0.0]
Service method parameter names will not change. [from 1.0.0]
Service method parameter types and return types will not change. [from 1.0.0]
Service method kind (unary vs streaming) will not change.
Names of messages and enums will not change. [from 1.0.0]
Numbers assigned to enum choices will not change.
Names of enum choices will not change. [from 1.0.0]
The location of messages and enums, i.e. whether they are declared at the top lexical scope or nested inside another message will not change. [from 1.0.0]
Package names and directory structure will not change. [from 1.0.0]
optional and repeated declarators of existing fields will not change. [from 1.0.0]
No existing symbol will be deleted. [from 1.0.0]

Note: guarantees marked [from 1.0.0] will go into effect when this repository is tagged with version number 1.0.0.

The following additive changes are allowed:

Adding new fields to existing messages.
Adding new messages or enums.
Adding new choices to existing enums.
Adding new choices to existing oneof fields.
Adding new services.
Adding new methods to existing services.

All the additive changes above must be accompanied by an explanation about how new and old senders and receivers that implement the version of the protocol before and after the change interoperate.

Experiments

New Experimental Components

Sometimes we need to experiment with new components, for example to add a completely new signal to OpenTelemetry. When designing a new signal, we recommend a "development" package to be used. This package will be used throughout development until reaching release candidate, in which case the development suffix is removed (e.g. v1 instead of v1development), creating a stable release package.

Such isolated experimental components are excluded from above stability requirements.

We recommend using Development, Alpha, Beta, Release Candidate levels to communicate different grades of readiness of new components. These levels MUST be communicated in the documentation of a message, field, etc. when the level does not match the stability of the package. For example, if a package is Stable but a field is not, the documentation MUST indicate that the field is experimental with the appropriate level (e.g. Alpha, Beta, etc). Conversely, individual Status annotations are not required if a component is the same maturity level as the package it is defined in.

Experimental components may be removed completely at the end of the experiment, provided that they are not referenced from any Stable component.

Experiments which succeed, require a review to be marked Stable. Once marked Stable they become subject to the stability requirements.

Experimental Additions to Stable Components

New experimental fields or messages may be added in Development state to Stable components. The experimental fields and messages within Stable components are subject to the full stability requirements.

When the stability of a portion of the protocol doesn't match the expectations of the package, there MUST be a stability annotation in the docs. For example:

// A reference to an Entity.
// Entity represents an object of interest associated with produced telemetry: e.g spans, metrics, profiles, or logs.
//
// Status: [Development]
message EntityRef {
  // ...
}

If an experiment concludes and the previously added field or message is not needed anymore, the field/message must stay, but it may be declared "deprecated". During all phases of experimentation it must be clearly specified that the field or message may be deprecated. Typically, deprecated fields are left empty by the senders and the recipients that participate in experiments must expect during all experimental phases (including after the experiment is concluded) that the experimental field or message has an empty value.

Experiments which succeed, require a review before the field or the message is marked Stable.

Generated Code

No guarantees are provided whatsoever about the stability of the code that is generated from the .proto files by any particular code generator.

Maintainers

For more information about the maintainer role, see the community repository.

Approvers

For more information about the approver role, see the community repository.

Emeritus Maintainers

Previously this package was maintained solely by the OpenTelemetry Technical Committee. It now has a dedicated maintainer role that is independent of the OpenTelemetry specification.

Emeritus Approvers

Previously the package had the same approvals as the specification, via OpenTelemetry Specification Sponsors. It now has a dedicated approver role that is independent of the OpenTelemetry specification.