Update to markdownlint-cli2 (#15448)

trask · web-flow · commit eeac17eea038 · 2025-11-25T09:54:03.000+02:00
diff --git a/.github/config/.markdownlint-cli2.yaml b/.github/config/.markdownlint-cli2.yaml
@@ -0,0 +1,19 @@
+# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+# and https://github.com/DavidAnson/markdownlint-cli2
+
+config:
+  ul-style: false
+  line-length: false
+  no-duplicate-heading:
+    siblings_only: true
+  ol-prefix:
+    style: ordered
+  no-inline-html: false
+  fenced-code-language: false
+  no-trailing-punctuation:
+    punctuation: ".,;:" # allowing exclamation points and question marks at end of sentences
+
+ignores:
+  - "**/build/**"
+  - "CHANGELOG.md"
+  - "licenses/licenses.md"
diff --git a/.github/config/markdownlint.yml b/.github/config/markdownlint.yml
diff --git a/.github/repository-settings.md b/.github/repository-settings.md
@@ -14,7 +14,7 @@ private admin repo.
 - `GRADLE_PUBLISH_KEY` - owned by [@trask](https://github.com/trask)
 - `GRADLE_PUBLISH_SECRET` - owned by [@trask](https://github.com/trask)
 - `NVD_API_KEY` - stored in OpenTelemetry-Java 1Password
-  - Generated at https://nvd.nist.gov/developers/request-an-api-key
+  - Generated at <https://nvd.nist.gov/developers/request-an-api-key>
   - Key is associated with [@trask](https://github.com/trask)'s gmail address
 - `SONATYPE_KEY` - owned by [@trask](https://github.com/trask)
 - `SONATYPE_USER` - owned by [@trask](https://github.com/trask)
diff --git a/.github/workflows/reusable-markdown-lint-check.yml b/.github/workflows/reusable-markdown-lint-check.yml
@@ -14,4 +14,4 @@ jobs:
 
       - name: Run markdownlint
         run: |
-          npx markdownlint-cli@0.46.0 -c .github/config/markdownlint.yml -p .gitignore **/*.md -i licenses/licenses.md
+          npx markdownlint-cli2@0.17.1 --config .github/config/.markdownlint-cli2.yaml "**/*.md"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,7 +6,6 @@ Before submitting new features or changes to current functionality, it is recomm
 [open an issue](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/new)
 and discuss your ideas or propose the changes you wish to make.
 
-
 ## Breaking Changes
 
 When your PR introduces a breaking change:
diff --git a/docs/contributing/documenting-instrumentation.md b/docs/contributing/documenting-instrumentation.md
@@ -69,11 +69,9 @@ Every javaagent instrumentation module should have a README.md file in the javaa
 | `property.name` | Type | Default | Description |
 ```
 
-
 **Note:** At some point we will likely automate the generation of this javaagent README.md file
 using the metadata.yaml file described below.
 
-
 ## Metadata.yaml Files
 
 Each instrumentation should have a `metadata.yaml` file in the root of the instrumentation directory
@@ -168,7 +166,6 @@ Some notes when writing descriptions:
   * Example: "This instrumentation enriches HTTP server spans with route information, and enables
     controller spans for Apache CXF JAX-WS web services (controller spans are disabled by default)."
 
-
 ### Semantic Conventions
 
 If the instrumentation adheres to one or more specific semantic conventions, include a
@@ -228,12 +225,10 @@ Each configuration should include:
 * `type`: The data type of the configuration value. Supported types are: `boolean`, `string`, `list`, and `map`.
 * `default`: The default value for the configuration.
 
-
 If a configuration enables experimental attributes, list them, for example:
 
 > Enables experimental span attributes `couchbase.operation_id` and `couchbase.local.address`.
 
-
 ### Classification (optional)
 
 If an instrumentation module does not specify a `classification`, it is assumed to be `library`.
@@ -251,7 +246,6 @@ The primary way this `classification` is used is to group and filter instrumenta
 utility in tooling and documentation. If you are unsure which classification to use, you can omit
 this field, and it will default to `library`.
 
-
 ### Disabled by Default (optional)
 
 If an instrumentation is disabled by default, set `disabled_by_default: true`. This indicates that
diff --git a/docs/contributing/running-tests.md b/docs/contributing/running-tests.md
@@ -100,13 +100,14 @@ old containers, images and volumes using `docker system prune --volumes`.
 For some container environments, such as rootless Podman or a remotely hosted Docker,
 testcontainers may need additional configuration to successfully run the tests.
 The following environment variables can be used for configuration:
+
 - `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE` - The location of the Docker socket on the host. Default is `/var/run/docker.sock`
 - `TESTCONTAINERS_HOST_OVERRIDE` - The hostname used for container-to-container communication. Default Docker is `localhost`, but rootless Podman uses `host.containers.internal`
 
-# Troubleshooting CI Test Failures
+## Troubleshooting CI Test Failures
 
 See [Troubleshooting CI Test Failures](../../CONTRIBUTING.md#troubleshooting-pr-build-failures) for common issues and solutions.
 
-# Debugging
+## Debugging
 
 For information on debugging tests or instrumentation, see [Debugging](debugging.md).
diff --git a/docs/contributing/style-guideline.md b/docs/contributing/style-guideline.md
@@ -102,7 +102,7 @@ Method parameters and local variables should never be declared `final`.
 
 ## `@Nullable` annotation usage
 
-**Note: this section is aspirational, as opposed to a reflection of the current codebase**
+**Note: this section is aspirational, as opposed to a reflection of the current codebase.**
 
 All parameters and fields which can be `null` should be annotated with `@Nullable`
 (specifically `javax.annotation.Nullable`, which is included by the
diff --git a/docs/contributing/writing-instrumentation-module.md b/docs/contributing/writing-instrumentation-module.md
@@ -407,6 +407,7 @@ In order to preserve compatibility with both instrumentation strategies, we have
 from the advice method annotations.
 
 We have three sets of instrumentation modules:
+
 - "inlined only": only compatible with "inlined", `isIndyModule` returns `false`.
 - "indy compatible": compatible with both "indy" and "inlined", do not override `isIndyModule`, advices are modified with `AdviceTransformer` to be made "indy native" or "inlined" at runtime.
 - "indy native": only compatible with "indy" `isIndyModule` returns `true`.
diff --git a/docs/contributing/writing-instrumentation.md b/docs/contributing/writing-instrumentation.md
@@ -282,7 +282,6 @@ You can use the `@RegisterExtension` annotation to make sure that the instrument
 picked up by JUnit. Then, return the same extension instance in the `testing()` method
 implementation so that it's used in all test scenarios implemented in the abstract class.
 
-
 ## Writing Java agent instrumentation
 
 Now that you have working and tested library instrumentation, implement the javaagent
diff --git a/instrumentation/aws-sdk/aws-sdk-2.2/library/README.md b/instrumentation/aws-sdk/aws-sdk-2.2/library/README.md
@@ -18,11 +18,13 @@ DynamoDbClient client = DynamoDbClient.builder()
 ```
 
 For SQS an additional step is needed
+
 ```java
 SqsClientBuilder sqsClientBuilder = SqsClient.builder();
 ...
 SqsClient sqsClient = telemetry.wrap(sqsClientBuilder.build());
 ```
+
 ```java
 SqsAsyncClientBuilder sqsAsyncClientBuilder = SqsAsyncClient.builder();
 ...
diff --git a/instrumentation/graphql-java/README.md b/instrumentation/graphql-java/README.md
@@ -1,12 +1,14 @@
-# Settings for the GraphQL instrumentation
+# GraphQL Instrumentation
+
+## Settings for the GraphQL instrumentation
 
 | System property                                                        | Type    | Default | Description                                                                                                                                                                                                             |
 |------------------------------------------------------------------------|---------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `otel.instrumentation.graphql.query-sanitizer.enabled`                 | Boolean | `true`  | Whether to remove sensitive information from query source that is added as span attribute.                                                                                                                              |
 | `otel.instrumentation.graphql.add-operation-name-to-span-name.enabled` | Boolean | `false` | Whether GraphQL operation name is added to the span name. <p>**WARNING**: GraphQL operation name is provided by the client and can have high cardinality. Use only when the server is not exposed to malicious clients. |
 | `otel.instrumentation.graphql.capture-query`                           | Boolean | `true`  | Whether to capture the query in `graphql.document` span attribute.                                                                                                                                                      |
 
-# Settings for the GraphQL 20 instrumentation
+## Settings for the GraphQL 20 instrumentation
 
 | System property                                             | Type    | Default | Description                                                                                                                       |
 |-------------------------------------------------------------|---------|---------|-----------------------------------------------------------------------------------------------------------------------------------|
diff --git a/instrumentation/jmx-metrics/README.md b/instrumentation/jmx-metrics/README.md
@@ -273,18 +273,22 @@ For other values of `stateName`, we have:
 - `tomcat.connector.status` value = `1`, attributes `port` = `8080` and `tomcat.connector.state` = `degraded`
 
 Each state key can be mapped to one or more values of the MBean attribute using:
+
 - a string literal or a string array
 - a `*` character to provide default option and avoid enumerating all values, this value must be quoted in YAML
 
 Exactly one `*` value must be present in the mapping to ensure all possible values of the MBean attribute can be mapped to a state key.
 
 The default value indicated by `*` does not require a dedicated state key. For example, if we want to have `tomcat.connector.state` metric attribute with values `on` or `off`, we can use:
+
 ```yaml
           tomcat.connector.state:
             on: STARTED
             off: [STOPPED,FAILED,'*']
 ```
+
 In the particular case where only two values are defined, we can simplify further by explicitly defining one state and rely on default for the other.
+
 ```yaml
           tomcat.connector.state:
             on: STARTED
@@ -301,7 +305,6 @@ For example, with JVM memory, the `java.lang:name=*,type=MemoryPool` MBeans have
 However, in the semantic conventions the metric attribute `jvm.memory.type` should be lower-cased to fit the `jvm.memory.used` definition, in this case we can
 apply the `lowercase` metric attribute transformation as follows:
 
-
 ```yaml
 ---
 rules:
@@ -312,7 +315,7 @@ rules:
         metric: jvm.memory.used
         unit: By
         metricAttribute:
-          jvm.memory.pool.name	: param(name)
+          jvm.memory.pool.name: param(name)
           jvm.memory.type: lowercase(beanattr(Type))
 ```
 
@@ -337,6 +340,7 @@ Currently available unit conversions:
 | ns           | s      |
 
 Example of defining unit conversion in yaml file:
+
 ```yaml
 rules:
   - beans:
@@ -350,6 +354,7 @@ rules:
         unit: s
         desc: The longest request processing time
 ```
+
 `sourceUnit` can also be defined on rule level (see [Making shortcuts](#making-shortcuts))
 
 ### Filtering negative values
@@ -396,11 +401,13 @@ where the `name` parameter in the MBean name is NOT mapped to a metric attribute
 ```
 
 When two or more MBean parameters are used, it is also possible to perform a partial aggregation:
+
 - parameters not mapped as metric attributes are discarded
 - parameters mapped as metric attributes with `param(<mbeanParam>)` are preserved
 - values are aggregated with mapped metric attributes
 
 The applied aggregation depends on the metric type:
+
 - `counter` or `updowncounter`: sum aggregation
 - `gauge`: last-value aggregation
 
diff --git a/instrumentation/jmx-metrics/library/jetty.md b/instrumentation/jmx-metrics/library/jetty.md
@@ -3,6 +3,7 @@
 Here is the list of metrics based on MBeans exposed by [Jetty](https://jetty.org/).
 
 The metrics captured and their respective attributes depend on the Jetty version:
+
 - [Jetty 12 and later](#jetty-12-and-later)
 - [Jetty 9 to 11](#jetty-9-to-11)
 
diff --git a/instrumentation/logback/logback-appender-1.0/library/README.md b/instrumentation/logback/logback-appender-1.0/library/README.md
@@ -107,5 +107,4 @@ The available settings are:
 | `captureEventName`                   | Boolean | `false` | Enable moving the `event.name` attribute (captured by one of the other mechanisms of capturing attributes) to the log event name.                                                                                                                 |
 | `numLogsCapturedBeforeOtelInstall`   | Integer | 1000    | Log telemetry is emitted after the initialization of the OpenTelemetry Logback appender with an OpenTelemetry object. This setting allows you to modify the size of the cache used to replay the first logs. thread.id attribute is not captured. |
 
-
 [source code attributes]: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#source-code-attributes
diff --git a/instrumentation/methods/README.md b/instrumentation/methods/README.md
@@ -1,4 +1,6 @@
-# Settings for the methods instrumentation
+# Methods Instrumentation
+
+## Settings for the methods instrumentation
 
 Provides a flexible way to capture telemetry at the method level in JVM applications. By weaving
 instrumentation into targeted methods at runtime based on the "otel.instrumentation.methods.include"
@@ -11,7 +13,7 @@ occurrences. The resulting data is automatically translated into OpenTelemetry t
 
 [cs]: https://opentelemetry.io/docs/zero-code/java/agent/annotations/#creating-spans-around-methods-with-otelinstrumentationmethodsinclude
 
-# Declarative Configuration Example
+## Declarative Configuration Example
 
 In addition to configuring method instrumentation via system properties, you can use declarative
 configuration files to specify which methods to trace. This approach allows for more flexible and
diff --git a/instrumentation/oshi/README.md b/instrumentation/oshi/README.md
@@ -1,9 +1,11 @@
-# Settings for the OSHI instrumentation
+# OSHI Instrumentation
+
+## Settings for the OSHI instrumentation
 
 | System property                                           | Type    | Default | Description              |
 |-----------------------------------------------------------| ------- | ------- |--------------------------|
 | `otel.instrumentation.oshi.experimental-metrics.enabled`  | Boolean | `false` | Enable the OSHI metrics. |
 
-# Using OSHI with OpenTelemetry Java agent
+## Using OSHI with OpenTelemetry Java agent
 
-Download oshi-core jar from  https://central.sonatype.com/artifact/com.github.oshi/oshi-core and place it on the class path. OpenTelemetry Java agent uses system class loader to load classes from the oshi-core jar that are used for the metrics.
+Download oshi-core jar from <https://central.sonatype.com/artifact/com.github.oshi/oshi-core> and place it on the class path. OpenTelemetry Java agent uses system class loader to load classes from the oshi-core jar that are used for the metrics.
diff --git a/instrumentation/runtime-telemetry/runtime-telemetry-java17/library/README.md b/instrumentation/runtime-telemetry/runtime-telemetry-java17/library/README.md
@@ -1,3 +1,5 @@
+# Runtime Telemetry Java 17
+
 The main entry point is the `RuntimeMetrics` class in the package `io.opentelemetry.instrumentation.runtimemetrics.java17`:
 
 ```java
