diff --git a/CHANGELOG.md b/CHANGELOG.md index d710c4a6..d04a1e17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ The full list of changes can be found in the compare view for the respective rel ### Added - docs: add response size limitation for HTTP body and gRPC messages. [#781](https://github.com/open-telemetry/opentelemetry-proto/pull/781) +- processcontext: add `ProcessContext` message from OTEP 4719 [#783](https://github.com/open-telemetry/opentelemetry-proto/pull/783) ### Changed 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/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..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,19 +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) | +| 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). @@ -85,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 new file mode 100644 index 00000000..3a27414c --- /dev/null +++ b/opentelemetry/proto/processcontext/v1development/process_context.proto @@ -0,0 +1,54 @@ +// 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. It is not part of OTLP and is not +// exchanged via the OpenTelemetry Collector. +// +// See OTEP 4719 for details of this mechanism. +// +// Status: [Development] +message ProcessContext { + // 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 + // 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; +}