From 6c626defb7a9ba1716365c4b1af511201e715672 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 6 Jan 2025 14:55:58 -0800 Subject: [PATCH] Add cross-file anchor link check (use lychee for markdown link checking) and fix broken links (#4345) --- .lychee.toml | 13 +++++++++++ .markdown_link_check_config.json | 22 ------------------- Makefile | 12 +++++----- oteps/0202-events-and-logs-api.md | 2 +- ...-metric-instrument-optional-refinements.md | 8 +++---- .../0146-metrics-prototype-scenarios.md | 2 +- .../0173-messaging-semantic-conventions.md | 6 ++--- oteps/trace/0174-http-semantic-conventions.md | 6 ++--- 8 files changed, 32 insertions(+), 39 deletions(-) create mode 100644 .lychee.toml delete mode 100644 .markdown_link_check_config.json diff --git a/.lychee.toml b/.lychee.toml new file mode 100644 index 00000000000..8868926f43c --- /dev/null +++ b/.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 diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json deleted file mode 100644 index d24172ea15c..00000000000 --- a/.markdown_link_check_config.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "ignorePatterns": [ - { - "pattern": "^https://github\\.com/open-telemetry/opentelemetry-specification/(issues|pull)" - } - ], - "replacementPatterns": [ - { - "pattern": "^/", - "replacement": "{{BASEURL}}/" - }, - { - "pattern": "^https://github.com/open-telemetry/opentelemetry-specification/(blob|tree)/main/(specification|supplementary-guidelines)/", - "replacement": "LINK-CHECK-ERROR-USE-LOCAL-PATH-TO-DOC-PAGE-NOT-EXTERNAL-URL/" - } - ], - "retryOn429": true, - "aliveStatusCodes": [ - 200, - 403 - ] -} diff --git a/Makefile b/Makefile index df3303cb034..91d6d7eb96c 100644 --- a/Makefile +++ b/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 . diff --git a/oteps/0202-events-and-logs-api.md b/oteps/0202-events-and-logs-api.md index b41151e7c27..f5e19bd5587 100644 --- a/oteps/0202-events-and-logs-api.md +++ b/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? diff --git a/oteps/metrics/0088-metric-instrument-optional-refinements.md b/oteps/metrics/0088-metric-instrument-optional-refinements.md index 46bff0eb82c..bc82a594609 100644 --- a/oteps/metrics/0088-metric-instrument-optional-refinements.md +++ b/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 diff --git a/oteps/metrics/0146-metrics-prototype-scenarios.md b/oteps/metrics/0146-metrics-prototype-scenarios.md index 1c112b111b6..410883b78b7 100644 --- a/oteps/metrics/0146-metrics-prototype-scenarios.md +++ b/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: diff --git a/oteps/trace/0173-messaging-semantic-conventions.md b/oteps/trace/0173-messaging-semantic-conventions.md index 091cfcd28b2..d56b54edf11 100644 --- a/oteps/trace/0173-messaging-semantic-conventions.md +++ b/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. diff --git a/oteps/trace/0174-http-semantic-conventions.md b/oteps/trace/0174-http-semantic-conventions.md index f2f34b94874..9d18833562f 100644 --- a/oteps/trace/0174-http-semantic-conventions.md +++ b/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.