Add cross-file anchor link check (use lychee for markdown link checking) and fix broken links

.lychee.toml

@@ -0,0 +1,13 @@
+include-fragments = true
+
+accept = ["200..=299", "403"]
+
+exclude  = [
+    # excluding links to pull requests and issues is done for performance
+    "^https://github.com/open-telemetry/opentelemetry-specification/(issue|pull)/\\d+$",
+    # TODO (trask) look into this
+    "^https://docs.google.com/document/d/1d0afxe3J6bQT-I6UbRXeIYNcTIyBQv4axfjKF4yvAPA/edit"
+]
+
+# better to be safe and avoid failures
+max-retries = 6

Makefile

@@ -27,11 +27,13 @@ misspell-correction:	$(MISSPELL)
 
 .PHONY: markdown-link-check
 markdown-link-check:
-	@if ! npm ls markdown-link-check; then npm install; fi
-	@for f in $(ALL_DOCS); do \
-		npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json $$f \
-			|| exit 1; \
-	done
+	docker run --rm \
+		--mount 'type=bind,source=$(PWD),target=/home/repo' \
+		lycheeverse/lychee \
+		--config home/repo/.lychee.toml \
+		--root-dir /home/repo \
+		-v \
+		home/repo
 
 # This target runs markdown-toc on all files that contain
 # a comment <!-- tocstop -->.

oteps/0202-events-and-logs-api.md

@@ -20,7 +20,7 @@ Here are a few situations that require recording of Events, there will be more.
   - Standalone events that occur when there is no span in progress, such as errors, user interaction events and web vitals.
 - Recording kubernetes events
 - Collector Entity events [link](https://docs.google.com/document/d/1Tg18sIck3Nakxtd3TFFcIjrmRO_0GLMdHXylVqBQmJA/edit)
-- Few other event systems described in [example mappings](../specification/logs/data-model.md#appendix-a-example-mappings) in the data model.
+- Few other event systems described in [example mappings](../specification/logs/data-model-appendix.md#appendix-a-example-mappings) in the data model.
 
 ### Can the current Log API interfaces be used for events?
 

oteps/metrics/0088-metric-instrument-optional-refinements.md

@@ -52,9 +52,9 @@ have three calling patterns (_Bound_, _Unbound_, and _Batch_) to
 capture measurements.  Asynchronous instruments (Observer and its
 refinements) use callbacks to capture measurements.
 
-All measurement APIs produce metric events consisting of [timestamp,
+All measurement APIs produce metric events consisting of timestamp,
 instrument descriptor, label set, and numerical
-value](../../specification/metrics/api.md#metric-event-format).  Synchronous instrument
+value.  Synchronous instrument
 events additionally have [Context](../../specification/context/README.md), describing
 properties of the associated trace and distributed correlation values.
 
@@ -107,8 +107,8 @@ without referring to the collection interval and without ambiguity.
 ### Last-value and Measure instruments
 
 Measure instruments do not define a Last Value relationship.  One
-reason is that [synchronous events can happen
-simultaneously](../../specification/metrics/api.md#time).
+reason is that synchronous events can happen
+simultaneously.
 
 For Measure instruments, it is possible to compute an aggregation that
 computes the last-captured value in a collection interval, but it is

oteps/metrics/0146-metrics-prototype-scenarios.md

@@ -3,7 +3,7 @@
 With the stable release of the tracing specification, the OpenTelemetry
 community is willing to spend more energy on metrics API/SDK. The goal is to get
 the metrics API/SDK specification to
-[`Experimental`](../../specification/versioning-and-stability.md#experimental)
+[`Experimental`](../../specification/versioning-and-stability.md#development)
 state by end of 5/2021, and make it
 [`Stable`](../../specification/versioning-and-stability.md#stable)
 before end of 2021:

oteps/trace/0173-messaging-semantic-conventions.md

@@ -3,7 +3,7 @@
 This document aims to capture scenarios and a road map, both of which will
 serve as a basis for [stabilizing](../../specification/versioning-and-stability.md#stable)
 the [existing semantic conventions for messaging](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/messaging),
-which are currently in an [experimental](../../specification/versioning-and-stability.md#experimental)
+which are currently in an [experimental](../../specification/versioning-and-stability.md#development)
 state. The goal is to declare messaging semantic conventions stable before the
 end of 2021.
 
@@ -19,14 +19,14 @@ and Service Bus, Amazon SQS, SNS, and Kinesis.
 
 Bringing the existing experimental semantic conventions for messaging to a
 stable state is a crucial step for users and instrumentation authors, as it
-allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability),
+allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability),
 and thus to ship and use stable instrumentation.
 
 ## Roadmap
 
 1. This OTEP, consisting of scenarios and a proposed roadmap, is approved and
    merged.
-2. [Stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability)
+2. [Stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability)
    for semantic conventions are approved and merged. This is not strictly related
    to semantic conventions for messaging but is a prerequisite for stabilizing any
    semantic conventions.

oteps/trace/0174-http-semantic-conventions.md

@@ -3,7 +3,7 @@
 This document aims to capture scenarios/open questions and a road map, both of
 which will serve as a basis for [stabilizing](../../specification/versioning-and-stability.md#stable)
 the [existing semantic conventions for HTTP](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/http),
-which are currently in an [experimental](../../specification/versioning-and-stability.md#experimental)
+which are currently in an [experimental](../../specification/versioning-and-stability.md#development)
 state. The goal is to declare HTTP semantic conventions stable before the
 end of Q1 2022.
 
@@ -16,7 +16,7 @@ and guidelines for instrumenting HTTP communication.
 
 Bringing the existing experimental semantic conventions for HTTP to a
 stable state is a crucial step for users and instrumentation authors, as it
-allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability),
+allows them to rely on [stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability),
 and thus to ship and use stable instrumentation.
 
 > NOTE. This OTEP captures a scope for changes should be done to existing
@@ -26,7 +26,7 @@ experimental semantic conventions for HTTP, but does not propose solutions.
 
 1. This OTEP, consisting of scenarios/open questions and a proposed roadmap, is
    approved and merged.
-2. [Stability guarantees](../../specification/versioning-and-stability.md#not-defined-semantic-conventions-stability)
+2. [Stability guarantees](../../specification/versioning-and-stability.md#semantic-conventions-stability)
    for semantic conventions are approved and merged. This is not strictly related
    to semantic conventions for HTTP but is a prerequisite for stabilizing any
    semantic conventions.