From 06f97c800f5814efbcd5b4cbc687e0ca2f1b1bc5 Mon Sep 17 00:00:00 2001 From: Ivo Anjo Date: Thu, 2 Apr 2026 12:12:06 +0100 Subject: [PATCH 1/5] Add `ProcessContext` message from OTEP 4719 As https://github.com/open-telemetry/opentelemetry-specification/pull/4719 looks to be merged soon, it came up as we were implementing this spec in the OTel eBPF Profiler (https://github.com/open-telemetry/opentelemetry-ebpf-profiler/pull/1181) that it'd be nice to stop copy-pasting the `process_context.proto` and it's time to add it to the proper place. This is my first contribution to this repo so please do point out if I missed something! I didn't touch the collector parts since this message is not expected to be processed by the collector directly. --- Makefile | 4 +- README.md | 1 + .../v1development/process_context.proto | 59 +++++++++++++++++++ 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 opentelemetry/proto/processcontext/v1development/process_context.proto diff --git a/Makefile b/Makefile index d63457e7..5088b46b 100644 --- a/Makefile +++ b/Makefile @@ -162,10 +162,10 @@ gen-ruby: $(PROTOC) --ruby_out=./$(PROTO_GEN_RUBY_DIR) --grpc-ruby_out=./$(PROTO_GEN_RUBY_DIR) opentelemetry/proto/collector/logs/v1/logs_service.proto $(PROTOC) --ruby_out=./$(PROTO_GEN_RUBY_DIR) --grpc-ruby_out=./$(PROTO_GEN_RUBY_DIR) opentelemetry/proto/collector/profiles/v1development/profiles_service.proto -# The Profiling protocol is still development. So it is excluded from the breaking-change check. +# The Profiling and ProcessContext protocols are still development. So they are excluded from the breaking-change check. .PHONY: breaking-change breaking-change: - $(BUF) breaking --against $(BUF_AGAINST) --config '{"version":"v1","breaking":{"ignore":["opentelemetry/proto/profiles", "opentelemetry/proto/collector/profiles"]}}' $(BUF_FLAGS) + $(BUF) breaking --against $(BUF_AGAINST) --config '{"version":"v1","breaking":{"ignore":["opentelemetry/proto/profiles", "opentelemetry/proto/collector/profiles", "opentelemetry/proto/processcontext"]}}' $(BUF_FLAGS) ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' | sort) diff --git a/README.md b/README.md index 477731f8..51ada8ee 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ components as indicated by the Maturity table below. | trace/\*
collector/trace/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | | logs/\*
collector/logs/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | | profiles/\*
collector/profiles/* | Development | [Development](docs/specification.md#json-protobuf-encoding) | +| processcontext/* | Development | [Development](docs/specification.md#json-protobuf-encoding) | (See [Versioning and Stability](https://github.com/open-telemetry/opentelemetry-specification/blob/a08d1f92f62acd4aafe4dfaa04ae7bf28600d49e/specification/versioning-and-stability.md) for definition of maturity levels). diff --git a/opentelemetry/proto/processcontext/v1development/process_context.proto b/opentelemetry/proto/processcontext/v1development/process_context.proto new file mode 100644 index 00000000..5f486f47 --- /dev/null +++ b/opentelemetry/proto/processcontext/v1development/process_context.proto @@ -0,0 +1,59 @@ +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +syntax = "proto3"; + +package opentelemetry.proto.processcontext.v1development; + +import "opentelemetry/proto/common/v1/common.proto"; +import "opentelemetry/proto/resource/v1/resource.proto"; + +option csharp_namespace = "OpenTelemetry.Proto.ProcessContext.V1Development"; +option java_multiple_files = true; +option java_package = "io.opentelemetry.proto.processcontext.v1development"; +option java_outer_classname = "ProcessContextProto"; +option go_package = "go.opentelemetry.io/proto/otlp/processcontext/v1development"; + +// ProcessContext represents the payload for the process context sharing mechanism. +// +// This message is designed to be published by OpenTelemetry SDKs via a memory-mapped +// region, allowing external readers (such as the OpenTelemetry eBPF Profiler) to +// discover and read resource attributes from instrumented processes without requiring +// direct integration or process activity. +// +// See OTEP 4719 for details of this mechanism. +// +// Status: [Development] +message ProcessContext { + // The resource attributes describing this process. + // + // Attribute keys MUST be unique (it is not allowed to have more than one + // attribute with the same key). The behavior of software that receives + // duplicated keys can be unpredictable. + // + // Attributes SHOULD follow OpenTelemetry semantic conventions where applicable. + // See: https://opentelemetry.io/docs/specs/semconv/ + opentelemetry.proto.resource.v1.Resource resource = 1; + + // Additional attributes to share with external readers that are not part of + // the standard Resource. [Optional] + // + // This field allows publishers to include supplementary key-value pairs that + // may be useful for external readers but are not part of the SDK's configured + // Resource. + // + // Consider adding any keys here to the profiles semantic conventions in + // https://opentelemetry.io/docs/specs/semconv/general/profiles/ + repeated opentelemetry.proto.common.v1.KeyValue attributes = 2; +} From 3bc14735ab3028cfa3ee75f81474d49e0dd2ea30 Mon Sep 17 00:00:00 2001 From: Ivo Anjo Date: Thu, 2 Apr 2026 14:07:20 +0100 Subject: [PATCH 2/5] Update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e907c2c..e18143ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ The full list of changes can be found in the compare view for the respective rel ### Added +- processcontext: processcontext: add `ProcessContext` message from OTEP 4719 [#783](https://github.com/open-telemetry/opentelemetry-proto/pull/783) + ### Changed ### Fixed From e6f6fa797c268ca5f27586c881059a8b92215566 Mon Sep 17 00:00:00 2001 From: Ivo Anjo Date: Thu, 2 Apr 2026 15:47:11 +0100 Subject: [PATCH 3/5] Apply suggestion from @florianl Co-authored-by: Florian Lehner --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e18143ef..4e8fd2e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ The full list of changes can be found in the compare view for the respective rel ### Added -- processcontext: processcontext: add `ProcessContext` message from OTEP 4719 [#783](https://github.com/open-telemetry/opentelemetry-proto/pull/783) +- processcontext: add `ProcessContext` message from OTEP 4719 [#783](https://github.com/open-telemetry/opentelemetry-proto/pull/783) ### Changed From ec83a054fb7735a60734b76a8edfcbaf93326715 Mon Sep 17 00:00:00 2001 From: Ivo Anjo Date: Wed, 8 Apr 2026 17:42:17 +0100 Subject: [PATCH 4/5] Minor: Simplify resource comment description to match profiles.proto --- .../processcontext/v1development/process_context.proto | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/opentelemetry/proto/processcontext/v1development/process_context.proto b/opentelemetry/proto/processcontext/v1development/process_context.proto index 5f486f47..c68e31a2 100644 --- a/opentelemetry/proto/processcontext/v1development/process_context.proto +++ b/opentelemetry/proto/processcontext/v1development/process_context.proto @@ -36,14 +36,8 @@ option go_package = "go.opentelemetry.io/proto/otlp/processcontext/v1development // // Status: [Development] message ProcessContext { - // The resource attributes describing this process. - // - // Attribute keys MUST be unique (it is not allowed to have more than one - // attribute with the same key). The behavior of software that receives - // duplicated keys can be unpredictable. - // - // Attributes SHOULD follow OpenTelemetry semantic conventions where applicable. - // See: https://opentelemetry.io/docs/specs/semconv/ + // The resource for this process. + // If this field is not set then no resource info is known. opentelemetry.proto.resource.v1.Resource resource = 1; // Additional attributes to share with external readers that are not part of From 7c6b7668fd21356855466c5a1d0435c96931b138 Mon Sep 17 00:00:00 2001 From: Ivo Anjo Date: Fri, 1 May 2026 12:36:20 +0100 Subject: [PATCH 5/5] Update repository docs to open scope slightly to other OTel protos See discussion on https://github.com/open-telemetry/opentelemetry-proto/pull/783 for the reasoning behind this. --- CONTRIBUTING.md | 2 +- README.md | 59 +++++++++++++------ docs/README.md | 3 +- docs/processcontext.md | 23 ++++++++ .../v1development/process_context.proto | 3 +- 5 files changed, 68 insertions(+), 22 deletions(-) create mode 100644 docs/processcontext.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b4c08ce..8aba98e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## Introduction -Welcome, and thank you for your interest in contributing to the OpenTelemetry Protocol (OTLP) Specification! Your contributions — big or small — are invaluable in shaping and improving this essential part of the OpenTelemetry ecosystem. +Welcome, and thank you for your interest in contributing to OpenTelemetry's protocol definitions! Your contributions — big or small — are invaluable in shaping and improving this essential part of the OpenTelemetry ecosystem. Whether you are fixing a small issue, updating documentation, or introducing a major improvement, we appreciate your efforts. If you're new to the project, don't hesitate to ask questions and seek guidance from the community. diff --git a/README.md b/README.md index 51ada8ee..a98e6683 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,27 @@ -# OpenTelemetry Protocol (OTLP) Specification +# OpenTelemetry Protobuf Definitions [![Build Check](https://github.com/open-telemetry/opentelemetry-proto/workflows/Build%20Check/badge.svg?branch=main)](https://github.com/open-telemetry/opentelemetry-proto/actions?query=workflow%3A%22Build+Check%22+branch%3Amain) -This repository contains the [OTLP protocol specification](docs/specification.md) -and the corresponding Language Independent Interface Types ([.proto files](opentelemetry/proto)). +This repository contains the protocol buffer definitions for [OTLP](#otlp) (the primary OpenTelemetry data delivery protocol), +and other [Protocols](#protocols) that share its common types and release machinery. -## Language Independent Interface Types +See [contribution guidelines](CONTRIBUTING.md) if you would like to make any changes. -The proto files can be consumed as GIT submodules or copied and built directly in the consumer project. +## Protocols -The compiled files are published to central repositories (Maven, ...) from OpenTelemetry client libraries. +### OTLP -See [contribution guidelines](CONTRIBUTING.md) if you would like to make any changes. +The primary OpenTelemetry data delivery protocol, used to export traces, +metrics, logs, and profiles via gRPC and HTTP. + +- Specification: [docs/specification.md](docs/specification.md) +- Proto files: everything under [opentelemetry/proto/](opentelemetry/proto/) except `processcontext/` -## OTLP/JSON +#### OTLP/JSON See additional requirements for [OTLP/JSON wire representation here](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#json-protobuf-encoding). -## Generate gRPC Client Libraries +#### Generate gRPC Client Libraries To generate the raw gRPC client libraries, use `make gen-${LANGUAGE}`. Currently supported languages are: @@ -31,20 +35,37 @@ To generate the raw gRPC client libraries, use `make gen-${LANGUAGE}`. Currently * python * ruby +### ProcessContext + +A non-OTLP protocol for sharing process-level resource attributes with +external readers (e.g. the [OpenTelemetry eBPF Profiler](https://github.com/open-telemetry/opentelemetry-ebpf-profiler)) +via memory-mapped regions. Not exchanged via gRPC, HTTP, or the +OpenTelemetry Collector. + +- Documentation: [docs/processcontext.md](docs/processcontext.md) +- Proto file: [opentelemetry/proto/processcontext/v1development/process_context.proto](opentelemetry/proto/processcontext/v1development/process_context.proto) +- Specification: [OTEP 4719](https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/profiles/4719-process-ctx.md) + +## Language Independent Interface Types + +The proto files can be consumed as GIT submodules or copied and built directly in the consumer project. + +The compiled files are published to central repositories (Maven, ...) from OpenTelemetry client libraries. + ## 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. -| Component | Binary Protobuf Maturity | JSON Maturity | -| --------- | --------------- | ------------- | -| common/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| resource/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| metrics/\*
collector/metrics/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| trace/\*
collector/trace/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| logs/\*
collector/logs/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | -| profiles/\*
collector/profiles/* | Development | [Development](docs/specification.md#json-protobuf-encoding) | -| processcontext/* | Development | [Development](docs/specification.md#json-protobuf-encoding) | +| Protocol | Component | Binary Protobuf Maturity | JSON Maturity | +| -------------- | ----------------------------------- | ------------------------ | ----------------------------------------------------------- | +| OTLP | common/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| OTLP | resource/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| OTLP | metrics/\*
collector/metrics/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| OTLP | trace/\*
collector/trace/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| OTLP | logs/\*
collector/logs/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) | +| OTLP | profiles/\*
collector/profiles/* | Development | [Development](docs/specification.md#json-protobuf-encoding) | +| ProcessContext | processcontext/* | Development | N/A | (See [Versioning and Stability](https://github.com/open-telemetry/opentelemetry-specification/blob/a08d1f92f62acd4aafe4dfaa04ae7bf28600d49e/specification/versioning-and-stability.md) for definition of maturity levels). @@ -86,7 +107,7 @@ before and after the change interoperate. ## Experiments -### New Experimental Components +### 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 diff --git a/docs/README.md b/docs/README.md index dd95f61a..651880a7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,7 @@ # OpenTelemetry Protocol (OTLP) -This is the specification of the OpenTelemetry Protocol (OTLP). +This is the specification of the OpenTelemetry Protocol (OTLP). For other +protocols hosted in this repository, see the top-level [README](../README.md). - [Design Goals](design-goals.md) - [Requirements](requirements.md) diff --git a/docs/processcontext.md b/docs/processcontext.md new file mode 100644 index 00000000..eaa25c48 --- /dev/null +++ b/docs/processcontext.md @@ -0,0 +1,23 @@ +# Process Context + +**Status:** [Development](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md) + +ProcessContext is a non-OTLP protocol for sharing process-level OpenTelemetry +resource attributes with external readers (e.g. the +[OpenTelemetry eBPF Profiler](https://github.com/open-telemetry/opentelemetry-ebpf-profiler)). + +This page is a quick orientation; the normative specification lives in +[OTEP 4719][otep]. + +## Relationship to OTLP + +ProcessContext is **not** part of OTLP: + +- It is not exchanged via gRPC or HTTP. +- It does not pass through the OpenTelemetry Collector. +- It carries only process-scoped resource attributes, not telemetry data. + +It lives in this repository because it shares OTLP's `common` and `resource` +proto types and benefits from the same versioning and release machinery. + +[otep]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/oteps/profiles/4719-process-ctx.md diff --git a/opentelemetry/proto/processcontext/v1development/process_context.proto b/opentelemetry/proto/processcontext/v1development/process_context.proto index c68e31a2..3a27414c 100644 --- a/opentelemetry/proto/processcontext/v1development/process_context.proto +++ b/opentelemetry/proto/processcontext/v1development/process_context.proto @@ -30,7 +30,8 @@ option go_package = "go.opentelemetry.io/proto/otlp/processcontext/v1development // This message is designed to be published by OpenTelemetry SDKs via a memory-mapped // region, allowing external readers (such as the OpenTelemetry eBPF Profiler) to // discover and read resource attributes from instrumented processes without requiring -// direct integration or process activity. +// direct integration or process activity. It is not part of OTLP and is not +// exchanged via the OpenTelemetry Collector. // // See OTEP 4719 for details of this mechanism. //