open-telemetry · thompson-tomo · Jul 18, 2025 · Jul 22, 2025 · Aug 15, 2025 · Aug 24, 2025
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [![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)
+This repository contains the [OTLP protocol specification](docs/specs/specification.md)
 and the corresponding Language Independent Interface Types ([.proto files](opentelemetry/proto)).
 
 ## Language Independent Interface Types
@@ -38,12 +38,12 @@ 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/\*<br>collector/metrics/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) |
-| trace/\*<br>collector/trace/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) |
-| logs/\*<br>collector/logs/* | Stable | [Stable](docs/specification.md#json-protobuf-encoding) |
-| profiles/\*<br>collector/profiles/* | Development | [Development](docs/specification.md#json-protobuf-encoding) |
+| common/* | Stable | [Stable](docs/specs/specification.md#json-protobuf-encoding) |
+| resource/* | Stable | [Stable](docs/specs/specification.md#json-protobuf-encoding) |
+| metrics/\*<br>collector/metrics/* | Stable | [Stable](docs/specs/specification.md#json-protobuf-encoding) |
+| trace/\*<br>collector/trace/* | Stable | [Stable](docs/specs/specification.md#json-protobuf-encoding) |
+| logs/\*<br>collector/logs/* | Stable | [Stable](docs/specs/specification.md#json-protobuf-encoding) |
+| profiles/\*<br>collector/profiles/* | Development | [Development](docs/specs/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/docs/README.md b/docs/README.md
@@ -1,8 +1,7 @@
-# OpenTelemetry Protocol (OTLP)
+# OpenTelemetry Protocol (OTLP) Docs
 
-This is the specification of the OpenTelemetry Protocol (OTLP).
+The below table defines how the OTLP docs get mounted to the Open Telemetry website.
 
-- [Design Goals](design-goals.md)
-- [Requirements](requirements.md)
-- [Specification](specification.md)
-- [SDK Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)
+|Folder|Website Destination|
+| --- | --- |
+|Spec | https://opentelemetry.io/docs/specs/otlp/|
diff --git a/docs/specs/README.md b/docs/specs/README.md
@@ -0,0 +1,23 @@
+<!-- markdownlint-disable-next-line first-line-heading -->
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: OTLP
+aliases:
+  - /docs/reference/specification/protocol/otlp
+  - /docs/specs/otel/protocol/otlp
+spelling:
+  cSpell:ignore backoff backpressure errdetails nanos proto reconnections retryable
+cascade:
+  body_class: otel-docs-spec
+  github_repo: &repo https://github.com/open-telemetry/opentelemetry-proto
+  path_base_for_github_subdir: tmp/otlp
+  github_project_repo: *repo
+--->
+
+# OpenTelemetry Protocol (OTLP)
+
+This is the specification of the OpenTelemetry Protocol (OTLP).
+
+- [Design Goals](design-goals.md)
+- [Requirements](requirements.md)
+- [Specification](specification.md)
+- [SDK Exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md)
diff --git a/docs/design-goals.md → docs/specs/design-goals.md b/docs/design-goals.md → docs/specs/design-goals.md
@@ -1,3 +1,7 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Design Goals
+--->
+
 # Design Goals for OpenTelemetry Wire Protocol
 
 We want to design a telemetry data exchange protocol that has the following characteristics:

diff --git a/docs/img/otlp-client-server.png → docs/specs/img/otlp-client-server.png b/docs/img/otlp-client-server.png → docs/specs/img/otlp-client-server.png
diff --git a/docs/img/otlp-concurrent.png → docs/specs/img/otlp-concurrent.png b/docs/img/otlp-concurrent.png → docs/specs/img/otlp-concurrent.png
diff --git a/docs/img/otlp-multi-destination.png → docs/specs/img/otlp-multi-destination.png b/docs/img/otlp-multi-destination.png → docs/specs/img/otlp-multi-destination.png
diff --git a/docs/img/otlp-request-response.png → docs/specs/img/otlp-request-response.png b/docs/img/otlp-request-response.png → docs/specs/img/otlp-request-response.png
diff --git a/docs/img/otlp-sequential.png → docs/specs/img/otlp-sequential.png b/docs/img/otlp-sequential.png → docs/specs/img/otlp-sequential.png
diff --git a/docs/requirements.md → docs/specs/requirements.md b/docs/requirements.md → docs/specs/requirements.md
@@ -1,3 +1,7 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Requirements
+--->
+
 # OpenTelemetry Protocol Requirements
 
 This document will drive OpenTelemetry Protocol design and RFC.

diff --git a/docs/specification.md → docs/specs/specification.md b/docs/specification.md → docs/specs/specification.md
@@ -1,17 +1,5 @@
-<!-- markdownlint-disable-next-line first-line-heading -->
 <!--- Hugo front matter used to generate the website version of this page:
-title: OTLP Specification
-linkTitle: OTLP
-aliases:
-  - /docs/reference/specification/protocol/otlp
-  - /docs/specs/otel/protocol/otlp
-spelling:
-  cSpell:ignore backoff backpressure errdetails nanos proto reconnections retryable
-cascade:
-  body_class: otel-docs-spec
-  github_repo: &repo https://github.com/open-telemetry/opentelemetry-proto
-  path_base_for_github_subdir: tmp/otlp
-  github_project_repo: *repo
+linkTitle: Specification
 --->
 
 # OpenTelemetry Protocol Specification
@@ -94,10 +82,10 @@ 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](../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,
-[ExportProfilesServiceRequest](../opentelemetry/proto/collector/profiles/v1development/profiles_service.proto) for profiles).
+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,
+[ExportProfilesServiceRequest](../../opentelemetry/proto/collector/profiles/v1development/profiles_service.proto) for profiles).
 The client continuously sends a sequence of requests to the server and expects
 to receive a response to each request:
 
@@ -170,7 +158,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
-[Export\<signal>ServiceResponse](../opentelemetry/proto/collector) message
+[Export\<signal>ServiceResponse](../../opentelemetry/proto/collector) message
 (`ExportTraceServiceResponse` for traces, `ExportMetricsServiceResponse` for
 metrics, `ExportLogsServiceResponse` for logs and
 `ExportProfilesServiceResponse` for profiles).
@@ -183,7 +171,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
-[Export\<signal>ServiceResponse](../opentelemetry/proto/collector)
+[Export\<signal>ServiceResponse](../../opentelemetry/proto/collector)
 message as in the [Full Success](#full-success) case.
 
 Additionally, the server MUST initialize the `partial_success` field
@@ -368,11 +356,11 @@ data while being throttled.
 
 #### OTLP/gRPC Service and Protobuf Definitions
 
-gRPC service definitions [are here](../opentelemetry/proto/collector).
+gRPC service definitions [are here](../../opentelemetry/proto/collector).
 
-Protobuf definitions for requests and responses [are here](../opentelemetry/proto).
+Protobuf definitions for requests and responses [are here](../../opentelemetry/proto).
 
-Please make sure to check the proto version and [maturity level](../README.md#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.
 
@@ -385,7 +373,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](../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
@@ -443,7 +431,7 @@ numbers or strings are accepted when decoding.
 The client and the server MUST set "Content-Type: application/json" request and
 response headers when sending JSON Protobuf encoded payload.
 
-For JSON payload examples see: [OTLP JSON request examples](../examples/README.md)
+For JSON payload examples see: [OTLP JSON request examples](../../examples/README.md)
 
 #### OTLP/HTTP Request
 
@@ -499,7 +487,7 @@ 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
-[Export\<signal>ServiceResponse](../opentelemetry/proto/collector) message
+[Export\<signal>ServiceResponse](../../opentelemetry/proto/collector) message
 (`ExportTraceServiceResponse` for traces, `ExportMetricsServiceResponse` for
 metrics, `ExportLogsServiceResponse` for logs and
 `ExportProfilesServiceResponse` for profiles).
@@ -512,7 +500,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
-[Export\<signal>ServiceResponse](../opentelemetry/proto/collector)
+[Export\<signal>ServiceResponse](../../opentelemetry/proto/collector)
 message as in the [Full Success](#full-success-1) case.
 
 Additionally, the server MUST initialize the `partial_success` field