[chore] Improve check/fix make targets

.prettierignore

@@ -1,4 +1,5 @@
 /.github
+/.chloggen
 
 # for the first iteration, we only reformat /docs/cloud* and will add the rest in individual PRs
 /docs/**

CONTRIBUTING.md

@@ -13,23 +13,23 @@ requirements and recommendations.
 
 - [Sign the CLA](#sign-the-cla)
 - [How to Contribute](#how-to-contribute)
-  * [Prerequisites](#prerequisites)
-  * [1. Modify the YAML model](#1-modify-the-yaml-model)
-    + [Schema files](#schema-files)
-  * [2. Update the markdown files](#2-update-the-markdown-files)
-    + [Hugo frontmatter](#hugo-frontmatter)
-  * [3. Verify the changes before committing](#3-verify-the-changes-before-committing)
-  * [4. Changelog](#4-changelog)
-    + [When to add a Changelog Entry](#when-to-add-a-changelog-entry)
+  - [Prerequisites](#prerequisites)
+  - [1. Modify the YAML model](#1-modify-the-yaml-model)
+    - [Schema files](#schema-files)
+  - [2. Update the markdown files](#2-update-the-markdown-files)
+    - [Hugo frontmatter](#hugo-frontmatter)
+  - [3. Verify the changes before committing](#3-verify-the-changes-before-committing)
+  - [4. Changelog](#4-changelog)
+    - [When to add a Changelog Entry](#when-to-add-a-changelog-entry)
       - [Examples](#examples)
-    + [Adding a Changelog Entry](#adding-a-changelog-entry)
-  * [5. Getting your PR merged](#5-getting-your-pr-merged)
+    - [Adding a Changelog Entry](#adding-a-changelog-entry)
+  - [5. Getting your PR merged](#5-getting-your-pr-merged)
 - [Automation](#automation)
-  * [Consistency Checks](#consistency-checks)
-  * [Auto formatting](#auto-formatting)
-  * [Markdown style](#markdown-style)
-  * [Misspell check](#misspell-check)
-  * [Markdown link check](#markdown-link-check)
+  - [Consistency Checks](#consistency-checks)
+  - [Auto formatting](#auto-formatting)
+  - [Markdown style](#markdown-style)
+  - [Misspell check](#misspell-check)
+  - [Markdown link check](#markdown-link-check)
 - [Updating the referenced specification version](#updating-the-referenced-specification-version)
 - [Making a Release](#making-a-release)
 - [Merging existing ECS conventions](#merging-existing-ecs-conventions)

Makefile

@@ -62,7 +62,7 @@ markdown-toc:
 	@for f in $(ALL_DOCS); do \
 		if grep -q '<!-- tocstop -->' $$f; then \
 			echo markdown-toc: processing $$f; \
-			npx --no -- markdown-toc --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \
+			npx --no -- markdown-toc --bullets "-" --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \
 		else \
 			echo markdown-toc: no TOC markers, skipping $$f; \
 		fi; \
@@ -117,12 +117,13 @@ fix-format:
 
 # Run all checks in order of speed / likely failure.
 .PHONY: check
-check: misspell markdownlint markdown-link-check check-format
+check: misspell markdownlint check-format markdown-toc markdown-link-check
+	git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1)
 	@echo "All checks complete"
 
 # Attempt to fix issues / regenerate tables.
 .PHONY: fix
-fix: table-generation misspell-correction fix-format
+fix: table-generation misspell-correction fix-format markdown-toc
 	@echo "All autofixes complete"
 
 .PHONY: install-tools

docs/cloudevents/cloudevents-spans.md

@@ -13,10 +13,10 @@ linkTitle: CloudEvents Spans
 - [Definitions](#definitions)
 - [Overview](#overview)
 - [Conventions](#conventions)
-  * [Spans](#spans)
-    + [Creation](#creation)
-    + [Processing](#processing)
-  * [Attributes](#attributes)
+  - [Spans](#spans)
+    - [Creation](#creation)
+    - [Processing](#processing)
+  - [Attributes](#attributes)
 
 <!-- tocstop -->
 

docs/database/database-metrics.md

@@ -16,15 +16,15 @@ and attributes but more may be added in the future.
 <!-- toc -->
 
 - [Connection pools](#connection-pools)
-  * [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage)
-  * [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax)
-  * [Metric: `db.client.connections.idle.min`](#metric-dbclientconnectionsidlemin)
-  * [Metric: `db.client.connections.max`](#metric-dbclientconnectionsmax)
-  * [Metric: `db.client.connections.pending_requests`](#metric-dbclientconnectionspending_requests)
-  * [Metric: `db.client.connections.timeouts`](#metric-dbclientconnectionstimeouts)
-  * [Metric: `db.client.connections.create_time`](#metric-dbclientconnectionscreate_time)
-  * [Metric: `db.client.connections.wait_time`](#metric-dbclientconnectionswait_time)
-  * [Metric: `db.client.connections.use_time`](#metric-dbclientconnectionsuse_time)
+  - [Metric: `db.client.connections.usage`](#metric-dbclientconnectionsusage)
+  - [Metric: `db.client.connections.idle.max`](#metric-dbclientconnectionsidlemax)
+  - [Metric: `db.client.connections.idle.min`](#metric-dbclientconnectionsidlemin)
+  - [Metric: `db.client.connections.max`](#metric-dbclientconnectionsmax)
+  - [Metric: `db.client.connections.pending_requests`](#metric-dbclientconnectionspending_requests)
+  - [Metric: `db.client.connections.timeouts`](#metric-dbclientconnectionstimeouts)
+  - [Metric: `db.client.connections.create_time`](#metric-dbclientconnectionscreate_time)
+  - [Metric: `db.client.connections.wait_time`](#metric-dbclientconnectionswait_time)
+  - [Metric: `db.client.connections.use_time`](#metric-dbclientconnectionsuse_time)
 
 <!-- tocstop -->
 

docs/database/database-spans.md

@@ -11,7 +11,7 @@ linkTitle: Client Calls
 <!-- toc -->
 
 - [Connection-level attributes](#connection-level-attributes)
-  * [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem)
+  - [Notes and well-known identifiers for `db.system`](#notes-and-well-known-identifiers-for-dbsystem)
 - [Call-level attributes](#call-level-attributes)
 - [Semantic Conventions for specific database technologies](#semantic-conventions-for-specific-database-technologies)
 

docs/dotnet/dotnet-aspnetcore-metrics.md

@@ -12,15 +12,15 @@ This article defines semantic conventions for ASP.NET Core metrics.
 
 - [Server](#server)
 - [Routing](#routing)
-  * [Metric: `aspnetcore.routing.match_attempts`](#metric-aspnetcoreroutingmatch_attempts)
+  - [Metric: `aspnetcore.routing.match_attempts`](#metric-aspnetcoreroutingmatch_attempts)
 - [Exceptions](#exceptions)
-  * [Metric: `aspnetcore.diagnostics.exceptions`](#metric-aspnetcorediagnosticsexceptions)
+  - [Metric: `aspnetcore.diagnostics.exceptions`](#metric-aspnetcorediagnosticsexceptions)
 - [Rate-limiting](#rate-limiting)
-  * [Metric: `aspnetcore.rate_limiting.active_request_leases`](#metric-aspnetcorerate_limitingactive_request_leases)
-  * [Metric: `aspnetcore.rate_limiting.request_lease.duration`](#metric-aspnetcorerate_limitingrequest_leaseduration)
-  * [Metric: `aspnetcore.rate_limiting.queued_requests`](#metric-aspnetcorerate_limitingqueued_requests)
-  * [Metric: `aspnetcore.rate_limiting.request.time_in_queue`](#metric-aspnetcorerate_limitingrequesttime_in_queue)
-  * [Metric: `aspnetcore.rate_limiting.requests`](#metric-aspnetcorerate_limitingrequests)
+  - [Metric: `aspnetcore.rate_limiting.active_request_leases`](#metric-aspnetcorerate_limitingactive_request_leases)
+  - [Metric: `aspnetcore.rate_limiting.request_lease.duration`](#metric-aspnetcorerate_limitingrequest_leaseduration)
+  - [Metric: `aspnetcore.rate_limiting.queued_requests`](#metric-aspnetcorerate_limitingqueued_requests)
+  - [Metric: `aspnetcore.rate_limiting.request.time_in_queue`](#metric-aspnetcorerate_limitingrequesttime_in_queue)
+  - [Metric: `aspnetcore.rate_limiting.requests`](#metric-aspnetcorerate_limitingrequests)
 
 <!-- tocstop -->
 

docs/dotnet/dotnet-dns-metrics.md

@@ -11,7 +11,7 @@ This article defines semantic conventions for DNS metrics emitted by .NET.
 <!-- toc -->
 
 - [DNS metrics](#dns-metrics)
-  * [Metric: `dns.lookup.duration`](#metric-dnslookupduration)
+  - [Metric: `dns.lookup.duration`](#metric-dnslookupduration)
 
 <!-- tocstop -->
 

docs/dotnet/dotnet-http-metrics.md

@@ -11,14 +11,14 @@ This article defines semantic conventions for HTTP metrics emitted by .NET compo
 <!-- toc -->
 
 - [HTTP client](#http-client)
-  * [Metric: `http.client.request.duration`](#metric-httpclientrequestduration)
-  * [Metric: `http.client.open_connections`](#metric-httpclientopen_connections)
-  * [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration)
-  * [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue)
-  * [Metric: `http.client.active_requests`](#metric-httpclientactive_requests)
+  - [Metric: `http.client.request.duration`](#metric-httpclientrequestduration)
+  - [Metric: `http.client.open_connections`](#metric-httpclientopen_connections)
+  - [Metric: `http.client.connection.duration`](#metric-httpclientconnectionduration)
+  - [Metric: `http.client.request.time_in_queue`](#metric-httpclientrequesttime_in_queue)
+  - [Metric: `http.client.active_requests`](#metric-httpclientactive_requests)
 - [HTTP server](#http-server)
-  * [Metric: `http.server.request.duration`](#metric-httpserverrequestduration)
-  * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests)
+  - [Metric: `http.server.request.duration`](#metric-httpserverrequestduration)
+  - [Metric: `http.server.active_requests`](#metric-httpserveractive_requests)
 
 <!-- tocstop -->
 

docs/exceptions/exceptions-logs.md

@@ -14,7 +14,7 @@ emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry
 
 - [Recording an Exception](#recording-an-exception)
 - [Attributes](#attributes)
-  * [Stacktrace Representation](#stacktrace-representation)
+  - [Stacktrace Representation](#stacktrace-representation)
 
 <!-- tocstop -->
 

docs/exceptions/exceptions-spans.md

@@ -13,7 +13,7 @@ exceptions associated with spans.
 
 - [Recording an Exception](#recording-an-exception)
 - [Attributes](#attributes)
-  * [Stacktrace Representation](#stacktrace-representation)
+  - [Stacktrace Representation](#stacktrace-representation)
 
 <!-- tocstop -->
 

docs/faas/aws-lambda.md

@@ -14,18 +14,18 @@ use cases.
 <!-- toc -->
 
 - [All triggers](#all-triggers)
-  * [AWS X-Ray Active Tracing Considerations](#aws-x-ray-active-tracing-considerations)
-    + [`xray-lambda` Propagator Functionality](#xray-lambda-propagator-functionality)
-    + [`xray-lambda` Propagator Configuration](#xray-lambda-propagator-configuration)
+  - [AWS X-Ray Active Tracing Considerations](#aws-x-ray-active-tracing-considerations)
+    - [`xray-lambda` Propagator Functionality](#xray-lambda-propagator-functionality)
+    - [`xray-lambda` Propagator Configuration](#xray-lambda-propagator-configuration)
 - [API Gateway](#api-gateway)
 - [SQS](#sqs)
-  * [SQS Event](#sqs-event)
-  * [SQS Message](#sqs-message)
+  - [SQS Event](#sqs-event)
+  - [SQS Message](#sqs-message)
 - [Examples](#examples)
-  * [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive)
-  * [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active)
-  * [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive)
-  * [SQS (Lambda tracing active)](#sqs-lambda-tracing-active)
+  - [API Gateway Request Proxy (Lambda tracing passive)](#api-gateway-request-proxy-lambda-tracing-passive)
+  - [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active)
+  - [SQS (Lambda tracing passive)](#sqs-lambda-tracing-passive)
+  - [SQS (Lambda tracing active)](#sqs-lambda-tracing-active)
 - [Resource Detector](#resource-detector)
 
 <!-- tocstop -->

docs/faas/faas-metrics.md

@@ -18,18 +18,18 @@ operations. By adding FaaS attributes to metric events it allows for finely tune
 <!-- toc -->
 
 - [Metric Instruments](#metric-instruments)
-  * [FaaS Instance](#faas-instance)
-    + [Metric: `faas.invoke_duration`](#metric-faasinvoke_duration)
-    + [Metric: `faas.init_duration`](#metric-faasinit_duration)
-    + [Metric: `faas.coldstarts`](#metric-faascoldstarts)
-    + [Metric: `faas.errors`](#metric-faaserrors)
-    + [Metric: `faas.invocations`](#metric-faasinvocations)
-    + [Metric: `faas.timeouts`](#metric-faastimeouts)
-    + [Metric: `faas.mem_usage`](#metric-faasmem_usage)
-    + [Metric: `faas.cpu_usage`](#metric-faascpu_usage)
-    + [Metric: `faas.net_io`](#metric-faasnet_io)
+  - [FaaS Instance](#faas-instance)
+    - [Metric: `faas.invoke_duration`](#metric-faasinvoke_duration)
+    - [Metric: `faas.init_duration`](#metric-faasinit_duration)
+    - [Metric: `faas.coldstarts`](#metric-faascoldstarts)
+    - [Metric: `faas.errors`](#metric-faaserrors)
+    - [Metric: `faas.invocations`](#metric-faasinvocations)
+    - [Metric: `faas.timeouts`](#metric-faastimeouts)
+    - [Metric: `faas.mem_usage`](#metric-faasmem_usage)
+    - [Metric: `faas.cpu_usage`](#metric-faascpu_usage)
+    - [Metric: `faas.net_io`](#metric-faasnet_io)
 - [References](#references)
-  * [Metric References](#metric-references)
+  - [Metric References](#metric-references)
 
 <!-- tocstop -->
 

docs/faas/faas-spans.md

@@ -16,18 +16,18 @@ See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.m
 <!-- toc -->
 
 - [General Attributes](#general-attributes)
-  * [Function Name](#function-name)
-  * [Difference between invocation and instance](#difference-between-invocation-and-instance)
+  - [Function Name](#function-name)
+  - [Difference between invocation and instance](#difference-between-invocation-and-instance)
 - [Incoming Invocations](#incoming-invocations)
-  * [Incoming FaaS Span attributes](#incoming-faas-span-attributes)
-  * [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes)
+  - [Incoming FaaS Span attributes](#incoming-faas-span-attributes)
+  - [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes)
 - [Outgoing Invocations](#outgoing-invocations)
 - [Function Trigger Type](#function-trigger-type)
-  * [Datasource](#datasource)
-  * [HTTP](#http)
-  * [PubSub](#pubsub)
-  * [Timer](#timer)
-  * [Other](#other)
+  - [Datasource](#datasource)
+  - [HTTP](#http)
+  - [PubSub](#pubsub)
+  - [Timer](#timer)
+  - [Other](#other)
 - [Example](#example)
 
 <!-- tocstop -->

docs/general/attributes.md

@@ -16,20 +16,20 @@ Particular operations may refer to or require some of these attributes.
 <!-- toc -->
 
 - [Server, client and shared network attributes](#server-client-and-shared-network-attributes)
-  * [Address and port attributes](#address-and-port-attributes)
-  * [Server attributes](#server-attributes)
-    + [`server.address`](#serveraddress)
-  * [Client attributes](#client-attributes)
-  * [Source and destination attributes](#source-and-destination-attributes)
-    + [Source](#source)
-    + [Destination](#destination)
-  * [Other network attributes](#other-network-attributes)
-    + [`network.peer.*` and `network.local.*` attributes](#networkpeer-and-networklocal-attributes)
+  - [Address and port attributes](#address-and-port-attributes)
+  - [Server attributes](#server-attributes)
+    - [`server.address`](#serveraddress)
+  - [Client attributes](#client-attributes)
+  - [Source and destination attributes](#source-and-destination-attributes)
+    - [Source](#source)
+    - [Destination](#destination)
+  - [Other network attributes](#other-network-attributes)
+    - [`network.peer.*` and `network.local.*` attributes](#networkpeer-and-networklocal-attributes)
       - [Client/server examples using `network.peer.*`](#clientserver-examples-using--networkpeer)
-        * [Simple client/server example](#simple-clientserver-example)
-        * [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy)
-        * [Client/server example with forward proxy](#clientserver-example-with-forward-proxy)
-    + [Network connection and carrier attributes](#network-connection-and-carrier-attributes)
+        - [Simple client/server example](#simple-clientserver-example)
+        - [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy)
+        - [Client/server example with forward proxy](#clientserver-example-with-forward-proxy)
+    - [Network connection and carrier attributes](#network-connection-and-carrier-attributes)
 - [General remote service attributes](#general-remote-service-attributes)
 - [General identity attributes](#general-identity-attributes)
 - [General thread attributes](#general-thread-attributes)

docs/general/logs.md

@@ -16,8 +16,8 @@ They may be used in any Log Record they apply to.
 
 - [General log identification attributes](#general-log-identification-attributes)
 - [Log Media](#log-media)
-  * [Log File](#log-file)
-  * [I/O Stream](#io-stream)
+  - [Log File](#log-file)
+  - [I/O Stream](#io-stream)
 
 <!-- tocstop -->
 

docs/general/metrics.md

@@ -10,17 +10,17 @@ aliases: [docs/specs/semconv/general/metrics-general]
 <!-- toc -->
 
 - [General Guidelines](#general-guidelines)
-  * [Name Reuse Prohibition](#name-reuse-prohibition)
-  * [Units](#units)
-  * [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters)
-    + [Pluralization](#pluralization)
-    + [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters)
-    + [Do not use `total`](#do-not-use-total)
+  - [Name Reuse Prohibition](#name-reuse-prohibition)
+  - [Units](#units)
+  - [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters)
+    - [Pluralization](#pluralization)
+    - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters)
+    - [Do not use `total`](#do-not-use-total)
 - [General Metric Semantic Conventions](#general-metric-semantic-conventions)
-  * [Instrument Naming](#instrument-naming)
-  * [Instrument Units](#instrument-units)
-  * [Instrument Types](#instrument-types)
-  * [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries)
+  - [Instrument Naming](#instrument-naming)
+  - [Instrument Units](#instrument-units)
+  - [Instrument Types](#instrument-types)
+  - [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries)
 
 <!-- tocstop -->
 

docs/http/http-metrics.md

@@ -15,14 +15,14 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 <!-- toc -->
 
 - [HTTP Server](#http-server)
-  * [Metric: `http.server.request.duration`](#metric-httpserverrequestduration)
-  * [Metric: `http.server.active_requests`](#metric-httpserveractive_requests)
-  * [Metric: `http.server.request.body.size`](#metric-httpserverrequestbodysize)
-  * [Metric: `http.server.response.body.size`](#metric-httpserverresponsebodysize)
+  - [Metric: `http.server.request.duration`](#metric-httpserverrequestduration)
+  - [Metric: `http.server.active_requests`](#metric-httpserveractive_requests)
+  - [Metric: `http.server.request.body.size`](#metric-httpserverrequestbodysize)
+  - [Metric: `http.server.response.body.size`](#metric-httpserverresponsebodysize)
 - [HTTP Client](#http-client)
-  * [Metric: `http.client.request.duration`](#metric-httpclientrequestduration)
-  * [Metric: `http.client.request.body.size`](#metric-httpclientrequestbodysize)
-  * [Metric: `http.client.response.body.size`](#metric-httpclientresponsebodysize)
+  - [Metric: `http.client.request.duration`](#metric-httpclientrequestduration)
+  - [Metric: `http.client.request.body.size`](#metric-httpclientrequestbodysize)
+  - [Metric: `http.client.response.body.size`](#metric-httpclientresponsebodysize)
 
 <!-- tocstop -->