diff --git a/README.md b/README.md index 7e534a878..683f393be 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,12 @@ -# Language Independent Interface Types For OpenTelemetry +# OpenTelemetry Protocol (OTLP) Specification [![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](specification/otlp.md) +and the corresponding Language Independent Interface Types ([.proto files](opentelemetry/proto)). + +## 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. diff --git a/RELEASING.md b/RELEASING.md index a3d267bb7..207d234a9 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -79,16 +79,11 @@ You can use `git log upstream/v$MAJOR.$((MINOR-1)).x..upstream/v$MAJOR.$MINOR.x or the Github [compare tool](https://github.com/open-telemetry/opentelemetry-proto/compare/) to view a summary of all commits since last release as a reference. -In addition, you can refer to -[CHANGELOG.md](https://github.com/open-telemetry/opentelemetry-proto/blob/main/CHANGELOG.md) +In addition, you can refer to [CHANGELOG.md](CHANGELOG.md) for a list of major changes since last release. ## Update release versions in documentations and CHANGELOG files -After releasing is done, you need to update -[README.md](https://github.com/open-telemetry/opentelemetry-proto/blob/main/README.md) and -[CHANGELOG.md](https://github.com/open-telemetry/opentelemetry-proto/blob/main/CHANGELOG.md). +After releasing is done, you need to update [README.md](README.md) and [CHANGELOG.md](CHANGELOG.md). -Create a PR to mark the new release in -[CHANGELOG.md](https://github.com/open-telemetry/opentelemetry-proto/blob/main/CHANGELOG.md) -on main branch. +Create a PR to mark the new release in [CHANGELOG.md](CHANGELOG.md) on main branch. diff --git a/specification/protocol/README.md b/specification/README.md similarity index 60% rename from specification/protocol/README.md rename to specification/README.md index 2d7ecec94..4797f16fc 100644 --- a/specification/protocol/README.md +++ b/specification/README.md @@ -5,4 +5,4 @@ This is the specification of new OpenTelemetry protocol (OTLP). - [Design Goals](design-goals.md). - [Requirements](requirements.md). - [Specification](otlp.md). -- [SDK Exporter](exporter.md). +- [SDK Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md). diff --git a/specification/protocol/design-goals.md b/specification/design-goals.md similarity index 100% rename from specification/protocol/design-goals.md rename to specification/design-goals.md diff --git a/specification/protocol/img/otlp-client-server.png b/specification/img/otlp-client-server.png similarity index 100% rename from specification/protocol/img/otlp-client-server.png rename to specification/img/otlp-client-server.png diff --git a/specification/protocol/img/otlp-concurrent.png b/specification/img/otlp-concurrent.png similarity index 100% rename from specification/protocol/img/otlp-concurrent.png rename to specification/img/otlp-concurrent.png diff --git a/specification/protocol/img/otlp-multi-destination.png b/specification/img/otlp-multi-destination.png similarity index 100% rename from specification/protocol/img/otlp-multi-destination.png rename to specification/img/otlp-multi-destination.png diff --git a/specification/protocol/img/otlp-request-response.png b/specification/img/otlp-request-response.png similarity index 100% rename from specification/protocol/img/otlp-request-response.png rename to specification/img/otlp-request-response.png diff --git a/specification/protocol/img/otlp-sequential.png b/specification/img/otlp-sequential.png similarity index 100% rename from specification/protocol/img/otlp-sequential.png rename to specification/img/otlp-sequential.png diff --git a/specification/protocol/otlp.md b/specification/otlp.md similarity index 94% rename from specification/protocol/otlp.md rename to specification/otlp.md index 83836ad47..d6c463228 100644 --- a/specification/protocol/otlp.md +++ b/specification/otlp.md @@ -1,6 +1,6 @@ # OpenTelemetry Protocol Specification -**Status**: [Stable](../document-status.md) +**Status**: [Stable](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md) The OpenTelemetry Protocol (OTLP) specification describes the encoding, transport, and delivery mechanism of telemetry data between telemetry sources, intermediate @@ -75,9 +75,9 @@ All server components MUST support the following transport compression options: After establishing the underlying gRPC transport, the client starts sending telemetry data using unary requests using [Export*ServiceRequest](https://github.com/open-telemetry/opentelemetry-proto) -messages ([ExportLogsServiceRequest](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/logs/v1/logs_service.proto) for logs, -[ExportMetricsServiceRequest](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/metrics/v1/metrics_service.proto) for metrics, -[ExportTraceServiceRequest](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto) for traces). +messages ([ExportLogsServiceRequest](../opentelemetry/proto/collector/logs/v1/logs_service.proto) for logs, +[ExportMetricsServiceRequest](../opentelemetry/proto/collector/metrics/v1/metrics_service.proto) for metrics, +[ExportTraceServiceRequest](../opentelemetry/proto/collector/trace/v1/trace_service.proto) for traces). The client continuously sends a sequence of requests to the server and expects to receive a response to each request: @@ -150,7 +150,7 @@ If the server receives an empty request (a request that does not carry any telemetry data) the server SHOULD respond with success. On success, the server response MUST be a -[ExportServiceResponse](https://github.com/open-telemetry/opentelemetry-proto/tree/main/opentelemetry/proto/collector) +[ExportServiceResponse](../opentelemetry/proto/collector) message (`ExportTraceServiceResponse` for traces, `ExportMetricsServiceResponse` for metrics and `ExportLogsServiceResponse` for logs). @@ -163,7 +163,7 @@ in case of a successful response. If the request is only partially accepted (i.e. when the server accepts only parts of the data and rejects the rest), the server response MUST be the same -[ExportServiceResponse](https://github.com/open-telemetry/opentelemetry-proto/tree/main/opentelemetry/proto/collector) +[ExportServiceResponse](../opentelemetry/proto/collector) message as in the [Full Success](#full-success) case. Additionally, the server MUST initialize the `partial_success` field @@ -347,14 +347,11 @@ data while being throttled. #### OTLP/gRPC Service and Protobuf Definitions -gRPC service definitions -[are here](https://github.com/open-telemetry/opentelemetry-proto/tree/master/opentelemetry/proto/collector). +gRPC service definitions [are here](../opentelemetry/proto/collector). -Protobuf definitions for requests and responses -[are here](https://github.com/open-telemetry/opentelemetry-proto/tree/master/opentelemetry/proto). +Protobuf definitions for requests and responses [are here](../opentelemetry/proto). -Please make sure to check the proto version and -[maturity level](https://github.com/open-telemetry/opentelemetry-proto/#maturity-level). +Please make sure to check the proto version and [maturity level](../README.md#maturity-level). Schemas for different signals may be at different maturity level - some stable, some in beta. @@ -367,8 +364,7 @@ The default network port for OTLP/gRPC is 4317. OTLP/HTTP uses Protobuf payloads encoded either in [binary format](#binary-protobuf-encoding) or in [JSON format](#json-protobuf-encoding). Regardless of the encoding the Protobuf schema of the messages is the same for -OTLP/HTTP and OTLP/gRPC as -[defined here](https://github.com/open-telemetry/opentelemetry-proto/tree/master/opentelemetry/proto). +OTLP/HTTP and OTLP/gRPC as [defined here](../opentelemetry/proto). OTLP/HTTP uses HTTP POST requests to send telemetry data from clients to servers. Implementations MAY use HTTP/1.1 or HTTP/2 transports. Implementations @@ -475,8 +471,7 @@ If the server receives an empty request (a request that does not carry any telemetry data) the server SHOULD respond with success. On success, the server MUST respond with `HTTP 200 OK`. The response body MUST be -a Protobuf-encoded -[ExportServiceResponse](https://github.com/open-telemetry/opentelemetry-proto/tree/main/opentelemetry/proto/collector) +a Protobuf-encoded [ExportServiceResponse](../opentelemetry/proto/collector) message (`ExportTraceServiceResponse` for traces, `ExportMetricsServiceResponse` for metrics and `ExportLogsServiceResponse` for logs). @@ -489,7 +484,7 @@ in case of a successful response. If the request is only partially accepted (i.e. when the server accepts only parts of the data and rejects the rest), the server MUST respond with `HTTP 200 OK`. The response body MUST be the same -[ExportServiceResponse](https://github.com/open-telemetry/opentelemetry-proto/tree/main/opentelemetry/proto/collector) +[ExportServiceResponse](../opentelemetry/proto/collector) message as in the [Full Success](#full-success-1) case. Additionally, the server MUST initialize the `partial_success` field diff --git a/specification/protocol/requirements.md b/specification/requirements.md similarity index 100% rename from specification/protocol/requirements.md rename to specification/requirements.md