[ci-cd] Add markdownlint for the repo

.github/workflows/build-and-test.yml

@@ -132,6 +132,10 @@ jobs:
       - run: make genotelcontribcol
       - name: CheckDoc
         run: make checkdoc
+      - name: MarkdownLint
+        run: make markdownlint
+      - name: Misspell
+        run: make misspell
       - name: CheckMetadata
         run: make checkmetadata
       - name: CheckApi

.markdownlint.yaml

@@ -0,0 +1,35 @@
+# markdownlint configuration for OpenTelemetry Collector
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+#
+# Start permissive to establish a baseline; tighten rules over time.
+default: true
+
+# Disabled rules (existing codebase has many violations)
+MD001: false  # heading increment
+MD004: false  # unordered list style
+MD007: false  # unordered list indentation
+MD013: false  # line length
+MD014: false  # dollar signs in commands
+MD022: false  # blanks around headings
+MD024: false  # duplicate headings
+MD025: false  # multiple top-level headings
+MD026: false  # trailing punctuation in heading
+MD029: false  # ordered list prefix
+MD030: false  # spaces after list markers
+MD031: false  # blanks around fences
+MD032: false  # blanks around lists
+MD033: false  # inline HTML
+MD034: false  # bare URLs
+MD036: false  # emphasis as heading
+MD038: false  # spaces in code spans
+MD040: false  # fenced code language
+MD041: false  # first line heading
+MD047: false  # single trailing newline
+MD049: false  # emphasis style
+MD051: false  # link fragments
+MD053: false  # unused link definitions
+MD058: false  # blanks around tables
+MD059: false  # descriptive link text
+MD060: false  # table column style
+MD028: false  # blank line inside blockquote
+MD037: false  # spaces inside emphasis

.markdownlintignore

@@ -0,0 +1,6 @@
+# Changelogs (autogenerated, chloggen manages structure)
+CHANGELOG.md
+CHANGELOG-API.md
+
+# GitHub templates (intentional structure/HTML)
+.github/

CHANGELOG.md

@@ -180,7 +180,7 @@ If you are looking for developer-facing changes, check out [CHANGELOG-API.md](./
   Previously:
   - the `service.instance.id` reported in the AgentDescription was based on the OpAMP instance UID
   - the instance UID was typically set based on the `service.instance.id` from the Collector resource attributes
-  - it could be overriden using the `instance_uid` configuration of the OpAMP extension
+  - it could be overridden using the `instance_uid` configuration of the OpAMP extension
 
   This meant that the reported `service.instance.id` did not always match the Collector resource attributes,
   which is a problem for correlation, and that server implementations got used to the typical case of

CONTRIBUTING.md

@@ -30,6 +30,11 @@ Replace `otel-config.yaml` with the appropriate configuration file as needed.
    testing it against the provided configuration.
 
 4. Lint your changes:
+
+ - Markdown lint for entrie project.
+  ```shell
+  make markdownlint
+  ```
 
  - For the entire project:
   ```shell
@@ -113,7 +118,9 @@ No changelog entry:
 The title for your pull-request should contain the component type and name in brackets, plus a short statement for your
 change. For instance:
 
-    [processor/tailsampling] fix AND policy
+```
+[processor/tailsampling] fix AND policy
+```
 
 Alternatively, if you have already written a changelog entry, you can set your PR title to `as per changelog` and a
 GitHub Action will automatically generate the PR title and description from your changelog entry YAML file(s). This
@@ -232,8 +239,8 @@ Following these steps for contributing additional metrics to existing receivers.
  - To generate new metrics on top of this updated YAML file.
    - Run `cd receiver/redisreceiver`
    - Run `go generate ./...`
-- Review the changed files and merge the changes into your forked repo.
-- Create PR from Github web console following the instructions above.
+ - Review the changed files and merge the changes into your forked repo.
+ - Create PR from Github web console following the instructions above.
 
 ## General Recommendations
 Below are some recommendations that apply to typical components. These are not rigid rules and there are exceptions but

Makefile

@@ -23,6 +23,13 @@ EX_INTERNAL=-not -path "./internal/*"
 EX_PKG=-not -path "./pkg/*"
 EX_CMD=-not -path "./cmd/*"
 
+# All source code and documents. Used in spell check.
+ALL_DOC := $(shell find . \( -name "*.md" -o -name "*.yaml" \) \
+                                -type f | sort)
+
+# All Markdown files. Used in markdownlint.
+ALL_MD := $(shell find . -name "*.md" -type f | sort)
+
 # This includes a final slash
 ROOT_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
 
@@ -601,6 +608,17 @@ build-examples:
 	docker build -t otelcontribcol-fpm internal/buildscripts/packaging/fpm
 	docker run --rm -v $(CURDIR):/repo -e PACKAGE=$* -e VERSION=$(VERSION) -e ARCH=$(ARCH) otelcontribcol-fpm
 
+
+# Runs lint for all markdown files
+.PHONY: markdownlint
+markdownlint:
+	npx -y markdownlint-cli@0.48.0 -c .markdownlint.yaml --ignore-path .markdownlintignore -- $(ALL_MD)
+
+# Fixes some of the markdown lint
+.PHONY: markdownlintfix
+markdownlintfix:
+	npx -y markdownlint-cli@0.48.0 -c .markdownlint.yaml --ignore-path .markdownlintignore --fix -- $(ALL_MD)
+
 # Verify existence of READMEs for components specified as default components in the collector.
 .PHONY: checkdoc
 checkdoc:

README.md

@@ -40,7 +40,7 @@
 
 # OpenTelemetry Collector Contrib
 
-This is a repository for OpenTelemetry Collector components that are not suitable for the  [core repository](https://github.com/open-telemetry/opentelemetry-collector) of the collector. 
+This is a repository for OpenTelemetry Collector components that are not suitable for the  [core repository](https://github.com/open-telemetry/opentelemetry-collector) of the collector.
 
 The official distributions, core and contrib, are available as part of the [opentelemetry-collector-releases](https://github.com/open-telemetry/opentelemetry-collector-releases) repository. Some of the components in this repository are part of the "core" distribution, such as the Jaeger and Prometheus components, but most of the components here are only available as part of the "contrib" distribution. Users of the OpenTelemetry Collector are also encouraged to build their own custom distributions with the [OpenTelemetry Collector Builder](https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder), using the components they need from the core repository, the contrib repository, and possibly third-party or internal repositories.
 
@@ -160,4 +160,4 @@ behavior. The facilitators will typically rely on codeowner's detailed review of
 when making the final approval decision.
 
 Marking the PR with the `ready to merge` label should only happen (by triagers/approvers/maintainers)
-once there is at least one approval from an approver, as per the description above. 
+once there is at least one approval from an approver, as per the description above.

cmd/opampsupervisor/specification/README.md

@@ -317,9 +317,9 @@ This results in the following Collector process invocation:
 If `extensions` are configured but the gate is disabled, the Supervisor
 will not start and the error message names the gate to enable.
 
-These are instances of extensions specific to the Supervisor and are 
+These are instances of extensions specific to the Supervisor and are
 distinct from any extensions configured to run inside the managed
-Collector configuration. Supervisor extensions are loaded and managed by the 
+Collector configuration. Supervisor extensions are loaded and managed by the
 Supervisor process itself.
 
 Supervisor extensions are configured under a top-level `extensions:` key

cmd/schemagen/README.md

@@ -11,13 +11,13 @@ and the generation process would be reversed – Go config files from schemas.
 
 ## Modes
 
-Script can generate schemas for components and packages. There are two distinct modes of operation: 
+Script can generate schemas for components and packages. There are two distinct modes of operation:
 `component` and `package`. Schemagen automatically detects the mode based on metadata.yaml file content.
 
 ### Component mode
 
 The `component` mode is aimed at generating configurations for individual components like receivers, processors,
-exporters, and connectors. 
+exporters, and connectors.
 
 In component mode, schema is generated in file named `config.schema.<ext>` to the chosen output folder
 (by default it's input directory). You can optionally specify the root struct to use for schema generation
@@ -83,7 +83,7 @@ componentOverrides:
     configName: 'FileLogConfig'
 ```
 
-- `namespace` corresponds to the Go package import path for modules from current repository. 
+- `namespace` corresponds to the Go package import path for modules from current repository.
   It is used to resolve references to other types within the same repository.
 - `mappings` tell schemagen how to treat specific selector expressions as
   primitive schema fields. Each mapping converts the Go type into a scalar

confmap/provider/aesprovider/README.md

@@ -28,15 +28,15 @@ openssl rand -base64 32
  Use placeholders with the following pattern `${aes:<encrypted & base64-encoded value>}` in a configuration. The value will be decrypted using the AES key provided in the environment variable `OTEL_AES_CREDENTIAL_PROVIDER`
 
 > For example:
-> 
+>
 > ```shell
 > export OTEL_AES_CREDENTIAL_PROVIDER="GQi+Y8HwOYzs8lAOjHUqB7vXlN8bVU2k0TAKtzwJzac="
 > ```
-> 
+>
 > ```yaml
 > password: ${aes:RsEf6cTWrssi8tlssfs1AJs2bRMrVm2Ce5TaWPY=}
 > ```
-> 
+>
 > will resolve to:
 > ```yaml
 > password: '1'

confmap/provider/googlesecretmanagerprovider/README.md

@@ -51,7 +51,6 @@ service:
 
 ### Prerequisites
 1. Make sure to enable access to the [Secret Manager API](https://cloud.google.com/secret-manager/docs/accessing-the-api).
-2. Make sure to [add the secret entries to Google Secret Manager](https://cloud.google.com/secret-manager/docs/create-secret-quickstart) before referencing them in the collector configurations. 
+2. Make sure to [add the secret entries to Google Secret Manager](https://cloud.google.com/secret-manager/docs/create-secret-quickstart) before referencing them in the collector configurations.
 3. This Provider interacts with Google Secret Manager using the Secret Manager client library. This library uses [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) to locate authentication credentials for Secret Manager. Therefore, if you run your collector in a local environment, execute the [`gcloud auth application-default login`](https://cloud.google.com/secret-manager/docs/authentication#client-libs) command to generate the necessary credential file to provide to ADC.
 4. However, if your collector runs on Google Compute Engine (GCE) or Google Kubernetes Engine (GKE), running `gcloud auth application-default login` is optional. This is because ADC can retrieve credentials via [the metadata server](https://cloud.google.com/docs/authentication/application-default-credentials#order). However, ensure that your GKE or GCE instance [has enabled the cloud-platform OAuth scope](https://cloud.google.com/secret-manager/docs/accessing-the-api#oauth-scopes). Additionally, verify that the Service Account attached to the GCE or GKE instance has been granted at least the [roles/secretmanager.secretAccessor](https://cloud.google.com/secret-manager/docs/access-control#secret-manager-roles) IAM role to access secret entries in Google Secret Manager.
-

connector/metricsaslogsconnector/README.md

@@ -82,7 +82,6 @@ connectors:
     include_scope_info: false
 ```
 
-
 ### Example Metric Conversions
 
 For a gauge metric `cpu_usage` with value `85.2`:
@@ -122,7 +121,7 @@ Each metric data point is converted to a log record with:
 - **Body**: Fixed JSON format: `{"metric_name": "$NAME", "value": "$VALUE"}`
 - **Timestamp**: Metric data point timestamp
 - **Observed Timestamp**: Metric data point start timestamp (if available)
-- **Attributes**: 
+- **Attributes**:
   - Original metric data point attributes (labels)
   - `metric.name`: The metric name
   - `metric.type`: The metric type (Gauge, Sum, Histogram, etc.)

connector/otlpjsonconnector/README.md

@@ -30,7 +30,6 @@
 > The old name `otlpjson` still works but is deprecated and will be removed in a future release.
 > Please update your configuration to use `otlp_json`.
 
-
 Allows to extract otlpjson data from incoming Logs and specifically the `Body` field.
 The data is written in
 [Protobuf JSON

connector/roundrobinconnector/README.md

@@ -47,7 +47,7 @@ connectors:
   round_robin:
 ```
 
-Preprocess data, then export using multiple exporter instances to scale the throughput if the exporter 
+Preprocess data, then export using multiple exporter instances to scale the throughput if the exporter
 does not support scale well (e.g. prometheusremotewrite).
 
 ```yaml

connector/servicegraphconnector/README.md

@@ -125,7 +125,7 @@ The following settings are required:
 
 - `latency_histogram_buckets`: the list of durations defining the latency histogram buckets. Make sure use either `latency_histogram_buckets` or `exponential_histogram_max_size`.
     - Default: `[2ms, 4ms, 6ms, 8ms, 10ms, 50ms, 100ms, 200ms, 400ms, 800ms, 1s, 1400ms, 2s, 5s, 10s, 15s]`
-- `exponential_histogram_max_size`: (no default) the maximum number of buckets per positive or negative number range. 
+- `exponential_histogram_max_size`: (no default) the maximum number of buckets per positive or negative number range.
 - `dimensions`: the list of dimensions to add together with the default dimensions defined above.
 
 The following settings can be optionally configured:

connector/signaltometricsconnector/README.md

@@ -150,10 +150,10 @@ gauge:
   value: <ottl_value_expression>
 ```
 
-- [**Required**] `value`represents an OTTL expression to extract a numeric value from 
-  the signal. Only OTTL expressions that return a value are accepted. The returned 
+- [**Required**] `value`represents an OTTL expression to extract a numeric value from
+  the signal. Only OTTL expressions that return a value are accepted. The returned
   value determines the value type of the `gauge` metric (`int` or `double`).
-  - For logs: Use e.g. `ExtractGrokPatterns` with a single key selector (see below). 
+  - For logs: Use e.g. `ExtractGrokPatterns` with a single key selector (see below).
   - For other signals: Use a field such as `value_int`, `value_double`, or a valid OTTL expression.
 
 **Examples:**

connector/spanmetricsconnector/README.md

@@ -27,7 +27,7 @@
 > The old name `spanmetrics` still works but is deprecated and will be removed in a future release.
 > Please update your configuration to use `span_metrics`.
 
-⚠️ Breaking Change Warning: 
+⚠️ Breaking Change Warning:
 The default duration metrics unit will change from `ms` to `s` to adhere to the OpenTelemetry semantic conventions and a feature gate `connector.spanmetrics.useSecondAsDefaultMetricsUnit` is also added.
 
 Currently, the feature gate is disabled by default, so the unit will remain `ms`. After one release cycle, the unit will switch to `s` and the feature gate will also be enabled by default.
@@ -115,7 +115,7 @@ The following settings can be optionally configured:
   - `disable` (default: `false`): Disable all histogram metrics.
   - `unit` (default: `ms`): The time unit for recording duration measurements.
   calculated from spans duration measurements. One of either: `ms` or `s`.
-  - `dimensions`: additional attributes to add as dimensions to the `traces.span.metrics.duration` metric, 
+  - `dimensions`: additional attributes to add as dimensions to the `traces.span.metrics.duration` metric,
   which will be included _on top of_ the common and configured `dimensions` for span attributes and resource attributes.
   - `explicit`:
     - `buckets`: the list of durations defining the duration histogram time buckets. Default
@@ -129,14 +129,14 @@ The following settings can be optionally configured:
   If the `name`d attribute is missing in the span, the optional provided `default` is used.
 
   If no `default` is provided, this dimension will be **omitted** from the metric.
-- `calls_dimensions`: additional attributes to add as dimensions to the `traces.span.metrics.calls` metric, 
+- `calls_dimensions`: additional attributes to add as dimensions to the `traces.span.metrics.calls` metric,
   which will be included _on top of_ the common and configured `dimensions` for span attributes and resource attributes.
-- `exclude_dimensions`: the list of dimensions to be excluded from the default set of dimensions. Use to exclude unneeded data from metrics. 
+- `exclude_dimensions`: the list of dimensions to be excluded from the default set of dimensions. Use to exclude unneeded data from metrics.
 - `dimensions_cache_size`: this setting is deprecated, please use aggregation_cardinality_limit instead.
 - `include_instrumentation_scope`: a list of instrumentation scope names to include from the traces.
 - `resource_metrics_cache_size` (default: `1000`): the size of the cache holding metrics for a service. This is mostly relevant for
    cumulative temporality to avoid memory leaks and correct metric timestamp resets.
-- `aggregation_temporality` (default: `AGGREGATION_TEMPORALITY_CUMULATIVE`): Defines the aggregation temporality of the generated metrics. 
+- `aggregation_temporality` (default: `AGGREGATION_TEMPORALITY_CUMULATIVE`): Defines the aggregation temporality of the generated metrics.
   One of either `AGGREGATION_TEMPORALITY_CUMULATIVE` or `AGGREGATION_TEMPORALITY_DELTA`.
 - `namespace` (default: `traces.span.metrics`): Defines the namespace of the generated metrics. If `namespace` provided, generated metric name will be added `namespace.` prefix.
 - `metrics_flush_interval` (default: `60s`): Defines the flush interval of the generated metrics.
@@ -274,8 +274,8 @@ For more example configuration covering various other use cases, please visit th
 ## Known Limitation: the Single Writer Principle
 
 Proper configuration of the `spanmetricsconnector` ensures compliance with the [Single Writer Principle](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#single-writer),
-which is a core requirement in the OpenTelemetry metrics data model. Misconfiguration, however, 
-may allow multiple components to write to the same metric stream, resulting in data inconsistency, 
+which is a core requirement in the OpenTelemetry metrics data model. Misconfiguration, however,
+may allow multiple components to write to the same metric stream, resulting in data inconsistency,
 metric conflicts, or the dropping of time series by metric backends.
 
 ### Why this happens
@@ -448,7 +448,7 @@ Custom web frameworks are a common source of high cardinality span names. While
 
 **Example: Custom Web Framework in Java**
 
-Consider a custom web framework that intercepts the generic route `/my-web-fwk/*` and dispatches requests like `/my-web-fwk/product/123456ABCD` or `/my-web-fwk/user/john.doe`. 
+Consider a custom web framework that intercepts the generic route `/my-web-fwk/*` and dispatches requests like `/my-web-fwk/product/123456ABCD` or `/my-web-fwk/user/john.doe`.
 
 The default Java Servlet instrumentation produces vague span names (`GET /my-web-fwk/*`), while directly using request URIs creates high cardinality (`GET /my-web-fwk/product/123456ABCD`).