Normalize paths to spec pages (#2703)

content/en/blog/2022/debug-otel-with-otel/index.md

@@ -250,7 +250,7 @@ COPY opentelemetry_module.conf /etc/nginx/conf.d
   /blog/2022/instrument-nginx/#put-nginx-between-two-services
 [localhost:16686]: http://localhost:16686/
 [http request & response headers]:
-  /docs/reference/specification/trace/semantic_conventions/http/#http-request-and-response-headers
+  /docs/specs/otel/trace/semantic_conventions/http/#http-request-and-response-headers
 [rfc7230]: https://httpwg.org/specs/rfc7230.html#field.order
 [added some checks to the nginx module]:
   https://github.com/open-telemetry/opentelemetry-cpp-contrib/pull/204

content/en/blog/2022/dotnet-instrumentation-first-beta.md

@@ -17,11 +17,11 @@ ASP.NET Core requests, you need to use the ASP.NET Core instrumentation package
 and initialize it with the OpenTelemetry SDK.
 
 Now, developers can use
-[automatic instrumentation](/docs/reference/specification/glossary/#automatic-instrumentation)
-to initialize [signal](/docs/reference/specification/glossary/#signals)
-providers and generate telemetry data for supported
-[instrumented libraries](/docs/reference/specification/glossary/#instrumented-library).
-This approach has several benefits:
+[automatic instrumentation](/docs/specs/otel/glossary/#automatic-instrumentation)
+to initialize [signal](/docs/specs/otel/glossary/#signals) providers and
+generate telemetry data for supported
+[instrumented libraries](/docs/specs/otel/glossary/#instrumented-library). This
+approach has several benefits:
 
 - A technical path forward to support automatic instrumentation via
   [byte-code instrumentation](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/v0.1.0-beta.1/docs/design.md#bytecode-instrumentations),

content/en/blog/2022/exponential-histograms/index.md

@@ -281,29 +281,27 @@ _A version of this article was [originally posted][] on the New Relic blog._
 [originally posted]: {{% param canonical_url %}}
 
 [percentiles]: https://en.wikipedia.org/wiki/Percentile
-[api]: /docs/reference/specification/metrics/api/
-[sdk]: /docs/reference/specification/metrics/sdk/
-[meter provider]: /docs/reference/specification/metrics/api/#meterprovider
-[instruments]: /docs/reference/specification/metrics/api/#instrument
+[api]: /docs/specs/otel/metrics/api/
+[sdk]: /docs/specs/otel/metrics/sdk/
+[meter provider]: /docs/specs/otel/metrics/api/#meterprovider
+[instruments]: /docs/specs/otel/metrics/api/#instrument
 [instrument selection]:
-  /docs/reference/specification/metrics/supplementary-guidelines/#instrument-selection
-[aggregation]: /docs/reference/specification/metrics/sdk/#aggregation
-[type of instrument]: /docs/reference/specification/metrics/api/#histogram
-[histogram-aggregation]:
-  /docs/reference/specification/metrics/sdk/#histogram-aggregations
+  /docs/specs/otel/metrics/supplementary-guidelines/#instrument-selection
+[aggregation]: /docs/specs/otel/metrics/sdk/#aggregation
+[type of instrument]: /docs/specs/otel/metrics/api/#histogram
+[histogram-aggregation]: /docs/specs/otel/metrics/sdk/#histogram-aggregations
 [explicit bucket histogram]:
-  /docs/reference/specification/metrics/sdk/#explicit-bucket-histogram-aggregation
+  /docs/specs/otel/metrics/sdk/#explicit-bucket-histogram-aggregation
 [explicit bucket histogram proto]:
   https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/metrics/v1/metrics.proto#L382
 [exponential bucket histogram]:
-  /docs/reference/specification/metrics/sdk/#base2-exponential-bucket-histogram-aggregation
+  /docs/specs/otel/metrics/sdk/#base2-exponential-bucket-histogram-aggregation
 [exponential bucket histogram proto]:
   https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/metrics/v1/metrics.proto#L463
 [example code]:
   https://github.com/jack-berg/newrelic-opentelemetry-examples/commit/2681bf25518c02f4e5830f89254c736e0959d306
-[otlp]: /docs/reference/specification/protocol/otlp/
+[otlp]: /docs/specs/otel/protocol/otlp/
 [opentelemetry-java]: https://github.com/open-telemetry/opentelemetry-java
-[environment variable]:
-  /docs/reference/specification/metrics/sdk_exporters/otlp/
+[environment variable]: /docs/specs/otel/metrics/sdk_exporters/otlp/
 [instrumentation]: /docs/instrumentation
 [github.com/open-telemetry]: https://github.com/open-telemetry

content/en/blog/2022/instrument-kafka-clients/index.md

@@ -22,8 +22,7 @@ difficult to track how messages are moved around. This is where OpenTelemetry
 comes into the picture. It provides multiple instrumentation libraries for
 adding tracing to messaging based applications. Of course, there is one for
 Apache Kafka clients. It also defines the specification of semantic conventions
-for
-[messaging systems](/docs/reference/specification/trace/semantic_conventions/messaging/).
+for [messaging systems](/docs/specs/otel/trace/semantic_conventions/messaging/).
 
 But usually, the architecture can even be more complicated: having applications
 not able to connect directly to the Apache Kafka cluster and talking its own

content/en/blog/2022/k8s-metadata/index.md

@@ -247,7 +247,7 @@ sidecar, or when one collector as an agent report to another collector.
 
 - [K8sattributes processor documentation][k8sattributesprocessor]
 - [K8sattributes processor RBAC](https://pkg.go.dev/github.com/open-telemetry/opentelemetry-collector-contrib/processor/k8sattributesprocessor#hdr-RBAC)
-- [OpenTelemetry Kubernetes attributes](/docs/reference/specification/resource/semantic_conventions/k8s)
+- [OpenTelemetry Kubernetes attributes](/docs/specs/otel/resource/semantic_conventions/k8s)
 - [Resource detector processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md)
 
 [pr#832]: https://github.com/open-telemetry/opentelemetry-operator/pull/832
@@ -256,5 +256,5 @@ sidecar, or when one collector as an agent report to another collector.
 [k8sattributesprocessor]:
   https://pkg.go.dev/github.com/open-telemetry/opentelemetry-collector-contrib/processor/k8sattributesprocessor
 [kubernetes resource semantic conventions]:
-  /docs/reference/specification/resource/semantic_conventions/k8s
+  /docs/specs/otel/resource/semantic_conventions/k8s
 [vert.x example app]: https://github.com/jaegertracing/vertx-create-span

content/en/blog/2022/knative/index.md

@@ -161,7 +161,7 @@ might not have an immediate impact on the user, however, it will enable users to
 start natively reporting data in OpenTelemetry format (OTLP).
 
 Another recently merged change is the addition of
-[Cloudevents semantic attributes into the OpenTelemetry specification](/docs/reference/specification/trace/semantic_conventions/cloudevents).
+[Cloudevents semantic attributes into the OpenTelemetry specification](/docs/specs/otel/trace/semantic_conventions/cloudevents).
 The document standardizes attributes related to CloudEvents. The screenshot
 below is from the demo application that is still not using the standardized
 attribute names:
@@ -209,5 +209,5 @@ instrumentation libraries explicitly in the code or even
 - [Zipkin B3](https://github.com/openzipkin/b3-propagation)
 - [W3C Trace-Context](https://www.w3.org/TR/trace-context/)
 - [OpenTelemetry instrumentation for Cloudevents Golang SDK](https://github.com/cloudevents/sdk-go/tree/main/observability/opentelemetry/v2)
-- [Cloudevents OpenTelemetry attributes](/docs/reference/specification/trace/semantic_conventions/cloudevents/)
+- [Cloudevents OpenTelemetry attributes](/docs/specs/otel/trace/semantic_conventions/cloudevents/)
 - [Knative tracing demo](https://github.com/pavolloffay/knative-tracing)

content/en/blog/2023/end-user-discussions-01.md

@@ -176,11 +176,11 @@ is no firm timeframe on when Python instrumentation will be marked as stable.
 #### 1- OpenTelemetry exemplars
 
 **Q:** Where can users learn more about
-[Exemplars](/docs/reference/specification/metrics/data-model/) and how they are
-being used in the real world?
+[Exemplars](/docs/specs/otel/metrics/data-model/) and how they are being used in
+the real world?
 
-**A:** [Exemplars](/docs/reference/specification/metrics/data-model/) are used
-to correlate OpenTelemetry [metrics](/docs/concepts/signals/metrics/) to
+**A:** [Exemplars](/docs/specs/otel/metrics/data-model/) are used to correlate
+OpenTelemetry [metrics](/docs/concepts/signals/metrics/) to
 [traces](/docs/concepts/signals/traces/). Exemplars are currently in the early
 stages of development, and more work still needs to be done. For more on the
 state of exemplars, check out the

content/en/blog/2023/end-user-q-and-a-01.md

@@ -121,9 +121,9 @@ To instrument their code, they configure the
 of
 [Node.JS auto-instrumentation plug-ins](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node).
 While the team is currently only using
-[auto-instrumentation](/docs/reference/specification/glossary/#automatic-instrumentation)
-to generate traces and [spans](/docs/concepts/observability-primer/#spans), they
-do occasionally add more data to a span (e.g.
+[auto-instrumentation](/docs/specs/otel/glossary/#automatic-instrumentation) to
+generate traces and [spans](/docs/concepts/observability-primer/#spans), they do
+occasionally add more data to a span (e.g.
 [attributes](/docs/concepts/signals/traces/#attributes)). They do this by
 grabbing the [context](/docs/concepts/signals/traces/#context-propagation) to
 find the span, and injecting custom attributes into that spans.
@@ -166,8 +166,8 @@ logs to their observability back-end. The ultimate goal is to have
 They have currently been able to automatically link traces to logs in ELK using
 [Node.JS Bunyan](https://nodejs.org/en/blog/module/service-logging-in-json-with-bunyan/).
 They are hoping to leverage
-[OpenTelemetry’s Exemplars](/docs/reference/specification/metrics/data-model/#exemplars)
-to link traces and metrics.
+[OpenTelemetry’s Exemplars](/docs/specs/otel/metrics/data-model/#exemplars) to
+link traces and metrics.
 
 ### How is the organization sending telemetry data to various observability back-ends?
 

content/en/blog/2023/end-user-q-and-a-02.md

@@ -81,9 +81,9 @@ The ultimate goal was to get folks to understand OpenTelemetry and the long-term
 vision around observability. Most developers are familiar and comfortable with
 logs – they just want to be able to write a log and see what happens. So, Doug
 started by getting developers to add
-[OpenTelemetry (structured) logs](/docs/reference/specification/logs/) to all of
-the services across their various platforms. In order to leverage OTel logs,
-developers had to add the
+[OpenTelemetry (structured) logs](/docs/specs/otel/logs/) to all of the services
+across their various platforms. In order to leverage OTel logs, developers had
+to add the
 [OpenTelemetry language-specific SDKs](/docs/concepts/sdk-configuration/) into
 their code. Once they got past that initial hump and got the SDKs into their
 code, it then became easier for developers to add
@@ -110,8 +110,7 @@ processing for deploying to the cloud.
 
 ### OTel logs are relatively new. Why use something so new?
 
-As one of the
-[newer OpenTelemetry signals](/docs/reference/specification/logs/), there was a
+As one of the [newer OpenTelemetry signals](/docs/specs/otel/logs/), there was a
 lot of concern around the maturity of logs. There were also many concerns about
 whether OTel itself would go away, or whether logs would be eliminated from the
 spec. All of that unease was put to rest once the folks at Uplight began

content/en/blog/2023/http-conventions-stability.md

@@ -6,9 +6,9 @@ author: '[Trask Stalnaker](https://github.com/trask) (Microsoft)'
 ---
 
 The OpenTelemetry community is beginning the final push to declare HTTP
-[tracing](/docs/reference/specification/trace/semantic_conventions/http/) and
-[metrics](/docs/reference/specification/metrics/semantic_conventions/http-metrics/)
-semantic conventions stable!
+[tracing](/docs/specs/otel/trace/semantic_conventions/http/) and
+[metrics](/docs/specs/otel/metrics/semantic_conventions/http-metrics/) semantic
+conventions stable!
 
 Following the recently proposed
 [Semantic Convention Process](https://docs.google.com/document/d/1ghvajKaipiNZso3fDtyNxU7x1zx0_Eyd02OGpMGEpLE),

content/en/blog/2023/otel-in-focus-02.md

@@ -19,7 +19,7 @@ channel.
 
 Here are the latest updates from our core repositories.
 
-##### [Specification](/docs/reference/specification/)
+##### [Specification](/docs/specs/otel/)
 
 [v1.18](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.18.0)
 has been released, with a batch of semantic convention updates and

content/en/blog/2023/otel-in-focus-03.md

@@ -20,7 +20,7 @@ channel.
 
 Here are the latest updates from our core repositories.
 
-##### [Specification](/docs/reference/specification/)
+##### [Specification](/docs/specs/otel/)
 
 [Version 1.19](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.19.0)
 has been released with a number of important udates.

content/en/blog/2023/otel-in-focus-04.md

@@ -20,7 +20,7 @@ channel.
 
 Here are the latest updates from some of our core repositories.
 
-##### [Specification](/docs/reference/specification/)
+##### [Specification](/docs/specs/otel/)
 
 [Version 1.20](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.20.0)
 has been released, and it's a big one!

content/en/blog/2023/sunsetting-opencensus.md

@@ -48,7 +48,7 @@ a "major version bump" and you may notice some changes in your telemetry.
 
 More details on what to expect and some suggested workflows for migration are
 outlined in the
-[OpenCensus Compatibility specification](/docs/reference/specification/compatibility/opencensus#migration-path)[^spec-next-release].
+[OpenCensus Compatibility specification](/docs/specs/otel/compatibility/opencensus#migration-path)[^spec-next-release].
 
 ## What to Expect After July 31st, 2023
 
@@ -89,12 +89,12 @@ One exception to this is the
 
 [^spec-next-release]:
     The
-    [OpenCensus Compatability specification](/docs/reference/specification/compatibility/opencensus/)
+    [OpenCensus Compatability specification](/docs/specs/otel/compatibility/opencensus/)
     is marked stable for the next specification release.
 
 [^shim-support]:
     These shims implement the stable
-    [OpenCensus Compatibility specification](/docs/reference/specification/compatibility/opencensus#migration-path)[^spec-next-release]
+    [OpenCensus Compatibility specification](/docs/specs/otel/compatibility/opencensus#migration-path)[^spec-next-release]
     and will be supported for at least one year following
-    [OpenTelemetry's long term support](/docs/reference/specification/versioning-and-stability/#long-term-support)
+    [OpenTelemetry's long term support](/docs/specs/otel/versioning-and-stability/#long-term-support)
     guidelines.

content/en/docs/collector/_index.md

@@ -66,6 +66,6 @@ progress of this effort, see `opentelemetry-collector-contrib` [issue #10116][].
 
 [issue #10116]:
   https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/10116
-[mixed]: /docs/reference/specification/document-status/#mixed
+[mixed]: /docs/specs/otel/document-status/#mixed
 [stability levels]:
   https://github.com/open-telemetry/opentelemetry-collector#stability-levels

content/en/docs/collector/deployment/agent.md

@@ -120,10 +120,10 @@ Cons:
 - Inflexible
 
 [instrumentation]: /docs/instrumentation/
-[otlp]: /docs/reference/specification/protocol/
+[otlp]: /docs/specs/otel/protocol/
 [collector]: /docs/collector/
 [instrument-java-metrics]: /docs/instrumentation/java/manual/#metrics
-[otlp-exporter]: /docs/reference/specification/protocol/exporter/
+[otlp-exporter]: /docs/specs/otel/protocol/exporter/
 [java-otlp-example]:
   https://github.com/open-telemetry/opentelemetry-java-docs/tree/main/otlp
 [py-otlp-example]:

content/en/docs/collector/deployment/gateway.md

@@ -154,10 +154,10 @@ Cons:
 - Higher overall resource usage (costs)
 
 [instrumentation]: /docs/instrumentation/
-[otlp]: /docs/reference/specification/protocol/
+[otlp]: /docs/specs/otel/protocol/
 [collector]: /docs/collector/
 [instrument-java-metrics]: /docs/instrumentation/java/manual/#metrics
-[otlp-exporter]: /docs/reference/specification/protocol/exporter/
+[otlp-exporter]: /docs/specs/otel/protocol/exporter/
 [java-otlp-example]:
   https://github.com/open-telemetry/opentelemetry-java-docs/tree/main/otlp
 [py-otlp-example]:

content/en/docs/collector/trace-receiver.md

@@ -1180,8 +1180,7 @@ concepts.
 ### Working with Resources
 
 In the OTel world, all telemetry is generated by a `Resource`, here is the
-definition according to the
-[OTel spec](/docs/reference/specification/resource/sdk):
+definition according to the [OTel spec](/docs/specs/otel/resource/sdk):
 
 > A `Resource` is an immutable representation of the entity producing telemetry
 > as Attributes. For example, a process producing telemetry that is running in a
@@ -1462,7 +1461,7 @@ minimize the conflicts across all the different types of telemetry generation
 entities that it may need to represent.
 
 These guidelines are known as Resource Semantic Conventions and are
-[documented in the OTel specification](/docs/reference/specification/resource/semantic_conventions/).
+[documented in the OTel specification](/docs/specs/otel/resource/semantic_conventions/).
 
 When creating your own attributes to represent your own telemetry generation
 entities, you should follow the guideline provided by the specification:
@@ -1502,17 +1501,15 @@ func fillResourceWithAtm(resource *pcommon.Resource, atm Atm){
 The resource semantic conventions also have prescriptive attribute names and
 well-known values to represent telemetry generation entities that are common and
 applicable across different domains like
-[compute unit](/docs/reference/specification/resource/semantic_conventions/#compute-unit),
-[environment](/docs/reference/specification/resource/semantic_conventions/#compute-unit)
-and others.
+[compute unit](/docs/specs/otel/resource/semantic_conventions/#compute-unit),
+[environment](/docs/specs/otel/resource/semantic_conventions/#compute-unit) and
+others.
 
 So, when you look at the `BackendSystem` entity, it has fields representing
-[OS](/docs/reference/specification/resource/semantic_conventions/os/) related
-information and
-[Cloud](/docs/reference/specification/resource/semantic_conventions/cloud/)
-related information, and we will use the attribute names and values prescribed
-by the resource semantic convention to represent that information on its
-`Resource`.
+[OS](/docs/specs/otel/resource/semantic_conventions/os/) related information and
+[Cloud](/docs/specs/otel/resource/semantic_conventions/cloud/) related
+information, and we will use the attribute names and values prescribed by the
+resource semantic convention to represent that information on its `Resource`.
 
 All the resource semantic convention attribute names and well known-values are
 kept within the
@@ -1959,8 +1956,8 @@ func appendTraceSpans(backend *BackendSystem, backendScopeSpans *ptrace.ScopeSpa
 > - Setting the `Name` of the span with the `Endpoint` field value from the
 >   `BackendSystem` instance
 > - Setting the `Kind` of the span as `ptrace.SpanKindServer`. Take a look at
->   [SpanKind section](/docs/reference/specification/trace/api/#spankind) within
->   the trace specification to understand how to properly define SpanKind.
+>   [SpanKind section](/docs/specs/otel/trace/api/#spankind) within the trace
+>   specification to understand how to properly define SpanKind.
 > - Used all the methods mentioned before to fill the `ptrace.Span` with the
 >   proper values to represent the `BackendSystem` operation
 

content/en/docs/collector/transforming-telemetry.md

@@ -80,9 +80,9 @@ processors:
 ```
 
 The resource processor has an identical configuration, but applies only to
-[resource attributes](/docs/reference/specification/resource/semantic_conventions/).
-Use the resource processor to modify infrastructure metadata related to
-telemetry. For example, this inserts the Kubernetes cluster name:
+[resource attributes](/docs/specs/otel/resource/semantic_conventions/). Use the
+resource processor to modify infrastructure metadata related to telemetry. For
+example, this inserts the Kubernetes cluster name:
 
 ```yaml
 processors:

content/en/docs/concepts/components.md

@@ -6,7 +6,7 @@ weight: 20
 
 OpenTelemetry is currently made up of several main components:
 
-- [Cross-language specification](/docs/reference/specification/)
+- [Cross-language specification](/docs/specs/otel/)
 - [OpenTelemetry Collector](/docs/collector/)
 - [Per-language SDKs](/docs/instrumentation/)
 - [Per-language instrumentation libraries](/docs/concepts/instrumenting-library/)
@@ -30,7 +30,7 @@ following:
 - **Data:** Defines the OpenTelemetry Protocol (OTLP) and vendor-agnostic
   semantic conventions that a telemetry backend can provide support for.
 
-For more information, see the [specification](/docs/reference/specification/).
+For more information, see the [specification](/docs/specs/otel/).
 
 Additionally, extensively-commented protobuf interface files for API concepts
 can be found in the