Add markdown link check (#5449)

* Add markdown link check

* Fix links

* update workflows

* move comment

.github/scripts/markdown_link_check_config.json

@@ -0,0 +1,11 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^https://github\\.com/open-telemetry/opentelemetry-java-instrumentation/pull/"
+    },
+    {
+      "pattern": "^https://mvnrepository\\.com/artifact/io\\.opentelemetry$"
+    }
+  ],
+  "retryOn429": true
+}

.github/workflows/ci.yml

@@ -191,12 +191,30 @@ jobs:
         run: ./gradlew muzzle --init-script ../../.github/scripts/local.init.gradle.kts
         working-directory: examples/extension
 
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2.3.4
+
+      - name: Check markdown links
+        run: |
+          npm install -g markdown-link-check
+          find . -type f \
+                 -name '*.md' \
+                 -not -path './.github/*' \
+                 -not -path './node_modules/*' \
+                 -print0 \
+            | xargs -0 -n1 markdown-link-check --config .github/scripts/markdown_link_check_config.json
+
   snapshot:
     runs-on: ubuntu-latest
     # intentionally not blocking snapshot publishing on testLatestDeps
     # because any time a new library version is released to maven central
     # it can fail due to test code incompatibility with the new library version,
     # or due to slight changes in emitted telemetry
+    #
+    # also not blocking snapshot publishing on markdown-link-check because links to external urls
+    # can break at any time
     needs: [ build, test, smoke-test, examples, muzzle ]
     if: ${{ github.ref_name == 'main' && github.repository == 'open-telemetry/opentelemetry-java-instrumentation' }}
     steps:

.github/workflows/nightly-no-cache.yml

@@ -174,6 +174,9 @@ jobs:
         run: ./gradlew muzzle --init-script ../../.github/scripts/local.init.gradle.kts
         working-directory: examples/extension
 
+  # markdown-link-check is intentionally not included in the nightly-no-cache build because
+  # it doesn't use gradle cache anyways and so is already covered by the normal nightly build
+
   issue:
     name: Open issue on failure
     needs: [ build, test, testLatestDeps, smoke-test, examples ]

.github/workflows/nightly.yml

@@ -182,9 +182,24 @@ jobs:
         run: ./gradlew muzzle --init-script ../../.github/scripts/local.init.gradle.kts
         working-directory: examples/extension
 
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2.3.4
+
+      - name: Check markdown links
+        run: |
+          npm install -g markdown-link-check
+          find . -type f \
+                 -name '*.md' \
+                 -not -path './.github/*' \
+                 -not -path './node_modules/*' \
+                 -print0 \
+            | xargs -0 -n1 markdown-link-check --config .github/scripts/markdown_link_check_config.json
+
   issue:
     name: Open issue on failure
-    needs: [ build, test, testLatestDeps, smoke-test, examples ]
+    needs: [ build, test, testLatestDeps, smoke-test, examples, markdown-link-check ]
     runs-on: ubuntu-latest
     if: always()
     steps:

.github/workflows/pr.yml

@@ -241,6 +241,9 @@ jobs:
         run: ./gradlew muzzle --init-script ../../.github/scripts/local.init.gradle.kts
         working-directory: examples/extension
 
+  # markdown-link-check is not included in the PR build because links to external urls can break at
+  # any time, which can be confusing for contributors
+
   accept-pr:
     needs: [ build, test, smoke-test, muzzle, examples ]
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -923,8 +923,8 @@ Due to an issue in the publishing infrastructure, a bad release was published as
 ### 🛠️ Bug fixes
 
 - gRPC context bridging issues
-  ([#2564](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issue/2564),
+  ([#2564](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/2564),
-  [#2959](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issue/2959))
+  [#2959](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/2959))
 - URL credentials of the form `https://username:password@www.example.com/` no longer captured
   ([#2707](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/2707))
 - Spring MVC instrumentation can cause Spring MVC to misroute requests under some conditions

CONTRIBUTING.md

@@ -16,7 +16,8 @@ See [Running the tests](./docs/contributing/running-tests.md) for more details.
 
 For developers testing code changes before a release is complete, there are
 snapshot builds of the `main` branch. They are available from
-the Sonatype OSS snapshots repository at https://oss.sonatype.org/content/repositories/snapshots/ ([browse](https://oss.sonatype.org/content/repositories/snapshots/io/opentelemetry/))
+the Sonatype OSS snapshots repository at `https://oss.sonatype.org/content/repositories/snapshots/`
+([browse](https://oss.sonatype.org/content/repositories/snapshots/io/opentelemetry/))
 
 #### Building from source
 

docs/java-7-rationale.md

@@ -39,10 +39,9 @@ running our "code under test" inside of Java 7. This is an attractive approach (
 does this, though not to run on older JVMs, but to run with the `-javaagent` flag because I didn't
 think about hacking the `-javaagent` flag directly into the test JVM). But this approach does come
 with a more complex testing and debugging story due to propagating tests and parameters, and
-debugging across two separate JVMs. And new contributor experience
+debugging across two separate JVMs. And new contributor experience has a very high priority for this
-[has a very high priority for this project](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/ga-requirements.md#p2)
+project (compared to say commercial tools who can invest more in onboarding their employees onto a
-(compared to say commercial tools who can invest more in onboarding their employees onto a more
+more complex codebase).
-complex codebase).
 
 ### Library (manual) instrumentation
 

instrumentation/aws-lambda/aws-lambda-core-1.0/library/README.md

@@ -79,7 +79,7 @@ requests and SQS requests. X-Ray propagation is always enabled, there is no need
 For API Gateway (HTTP) requests instrumented by using one of following methods:
 - extending `TracingRequestStreamHandler` or `TracingRequestHandler`
 - wrapping with `TracingRequestStreamWrapper` or `TracingRequestApiGatewayWrapper`
-traces can be propagated with supported HTTP headers (see https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/trace_propagators).
+traces can be propagated with supported HTTP headers (see https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/trace-propagators).
 
 In order to enable requested propagation for a handler, configure it on the SDK you build.
 

instrumentation/aws-lambda/aws-lambda-events-2.2/library/README.md

@@ -111,7 +111,7 @@ requests and SQS requests. X-Ray propagation is always enabled, there is no need
 For API Gateway (HTTP) requests instrumented by using one of following methods:
 - extending `TracingRequestStreamHandler` or `TracingRequestHandler`
 - wrapping with `TracingRequestStreamWrapper` or `TracingRequestApiGatewayWrapper`
-traces can be propagated with supported HTTP headers (see https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/trace_propagators).
+traces can be propagated with supported HTTP headers (see https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/trace-propagators).
 
 In order to enable requested propagation for a handler, configure it on the SDK you build.
 

instrumentation/spring/README.md

@@ -10,7 +10,7 @@ The [second section](#manual-instrumentation-using-handlers-and-filters)  will b
 
 The [third section](#auto-instrumentation-using-spring-starters) with build on the first two sections. We will use spring auto-configurations and instrumentation tools packaged in OpenTelemetry [Spring Starters](starters) to streamline the set up of OpenTelemetry using Spring. With these tools you will be able to setup distributed tracing with little to no changes to existing configurations and easily customize traces with minor additions to application code.
 
-In this guide we will be using a running example. In section one and two, we will create two spring web services using Spring Boot. We will then trace requests between these services using two different approaches. Finally, in section three we will explore tools documented in [opentelemetry-spring-boot-autoconfigure](/spring-boot-autoconfigure/README.md#features) which can improve this process.
+In this guide we will be using a running example. In section one and two, we will create two spring web services using Spring Boot. We will then trace requests between these services using two different approaches. Finally, in section three we will explore tools documented in [opentelemetry-spring-boot-autoconfigure](./spring-boot-autoconfigure/README.md#features) which can improve this process.
 
 # Settings 
 
@@ -751,7 +751,7 @@ public class TimeServiceApplication {
 
 ### Generating Trace - LoggingSpanExporter
 
-To generate a trace, run MainServiceApplication and TimeServiceApplication, and then send a request to `localhost:8080/message`. Shown below is the output of the default span exporter - (LoggingSpanExporter)[https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/logging].
+To generate a trace, run MainServiceApplication and TimeServiceApplication, and then send a request to `localhost:8080/message`. Shown below is the output of the default span exporter - [LoggingSpanExporter](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/logging).
 
 #### MainService
 

instrumentation/spring/spring-boot-autoconfigure/README.md

@@ -372,7 +372,7 @@ public class OpenTelemetryConfig {}
 
 This package provides auto configurations for [OTLP](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp), [Jaeger](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/jaeger), [Zipkin](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/zipkin), and [Logging](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/logging) Span Exporters.
 
-If an exporter is present in the classpath during runtime and a spring bean of the exporter is missing from the spring application context. An exporter bean is initialized and added to a simple span processor in the active tracer provider. Check out the implementation [here](/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/OpenTelemetryAutoConfiguration.java).
+If an exporter is present in the classpath during runtime and a spring bean of the exporter is missing from the spring application context. An exporter bean is initialized and added to a simple span processor in the active tracer provider. Check out the implementation [here](./src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/OpenTelemetryAutoConfiguration.java).
 
 
 #### Configuration Properties
@@ -381,32 +381,32 @@ If an exporter is present in the classpath during runtime and a spring bean of t
 
 | Feature          | Property                                 | Default Value | ConditionalOnClass     |
 |------------------|------------------------------------------|---------------|------------------------|
-| spring-web       | otel.springboot.httpclients.enabled      | true          | RestTemplate           |
+| spring-web       | otel.springboot.httpclients.enabled      | `true`        | RestTemplate           |
-| spring-webmvc    | otel.springboot.httpclients.enabled      | true          | OncePerRequestFilter   |
+| spring-webmvc    | otel.springboot.httpclients.enabled      | `true`        | OncePerRequestFilter   |
-| spring-webflux   | otel.springboot.httpclients.enabled      | true          | WebClient              |
+| spring-webflux   | otel.springboot.httpclients.enabled      | `true`        | WebClient              |
-| @WithSpan        | otel.springboot.aspects.enabled          | true          | WithSpan, Aspect       |
+| @WithSpan        | otel.springboot.aspects.enabled          | `true`        | WithSpan, Aspect       |
-| Otlp Exporter    | otel.exporter.otlp.enabled               | true          | OtlpGrpcSpanExporter   |
+| Otlp Exporter    | otel.exporter.otlp.enabled               | `true`        | OtlpGrpcSpanExporter   |
-| Jaeger Exporter  | otel.exporter.jaeger.enabled             | true          | JaegerGrpcSpanExporter |
+| Jaeger Exporter  | otel.exporter.jaeger.enabled             | `true`        | JaegerGrpcSpanExporter |
-| Zipkin Exporter  | otel.exporter.zipkin.enabled             | true          | ZipkinSpanExporter     |
+| Zipkin Exporter  | otel.exporter.zipkin.enabled             | `true`        | ZipkinSpanExporter     |
-| Logging Exporter | otel.exporter.logging.enabled            | true          | LoggingSpanExporter    |
+| Logging Exporter | otel.exporter.logging.enabled            | `true`        | LoggingSpanExporter    |
 
 <!-- Slf4j Log Correlation  otel.springboot.loggers.slf4j.enabled		true   		org.slf4j.MDC -->
 
 ##### Exporter Properties
 
 | Feature         | Property                      | Default Value                        |
-|-----------------|-------------------------------|------------------------------------|
+|-----------------|-------------------------------|--------------------------------------|
-| Otlp Exporter   | otel.exporter.otlp.endpoint   | localhost:4317                    |
+| Otlp Exporter   | otel.exporter.otlp.endpoint   | `localhost:4317`                     |
-|                 | otel.exporter.otlp.timeout    | 1s                                 |
+|                 | otel.exporter.otlp.timeout    | `1s`                                 |
-| Jaeger Exporter | otel.exporter.jaeger.endpoint | localhost:14250                    |
+| Jaeger Exporter | otel.exporter.jaeger.endpoint | `localhost:14250`                    |
-|                 | otel.exporter.jaeger.timeout  | 1s                                 |
+|                 | otel.exporter.jaeger.timeout  | `1s`                                 |
-| Zipkin Exporter | otel.exporter.jaeger.endpoint | http://localhost:9411/api/v2/spans |
+| Zipkin Exporter | otel.exporter.jaeger.endpoint | `http://localhost:9411/api/v2/spans` |
 
 ##### Tracer Properties
 
 | Feature | Property                        | Default Value |
-|---------|--------------------------------|---------------|
+|---------|---------------------------------|---------------|
-| Tracer  | otel.traces.sampler.probability | 1.0           |
+| Tracer  | otel.traces.sampler.probability | `1.0`         |
 
 ### Starter Guide