open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add Makefile target to auto-generate TOC via markdown-toc (#2020)

This commit is contained in:
Yuri Shkuro 2021-10-15 11:04:22 -04:00 committed by GitHub
parent 540878944d
commit d9fbb6f32c
11 changed files with 71 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -24,3 +24,7 @@ bin
# Misspell binary # Misspell binary
internal/tools/bin internal/tools/bin
# Node.js files for tools (e.g. markdown-toc)
node_modules/
package-lock.json

37
Makefile
View File

@ -5,8 +5,9 @@ PWD := $(shell pwd)
TOOLS_DIR := ./internal/tools TOOLS_DIR := ./internal/tools
MISSPELL_BINARY=bin/misspell MISSPELL_BINARY=bin/misspell
MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
MARKDOWN_LINK_CHECK=markdown-link-check MARKDOWN_LINK_CHECK=./node_modules/.bin/markdown-link-check
MARKDOWN_LINT=markdownlint MARKDOWN_LINT=./node_modules/.bin/markdownlint
MARKDOWN_TOC=./node_modules/.bin/markdown-toc
# see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
# Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
@ -27,17 +28,39 @@ misspell-correction:
.PHONY: install-markdown-link-check .PHONY: install-markdown-link-check
install-markdown-link-check: install-markdown-link-check:
# TODO: Check for existence before installing npm install markdown-link-check
npm install -g $(MARKDOWN_LINK_CHECK)
.PHONY: markdown-link-check .PHONY: markdown-link-check
markdown-link-check: markdown-link-check:
@for f in $(ALL_DOCS); do $(MARKDOWN_LINK_CHECK) --quiet --config .markdown_link_check_config.json $$f; done @for f in $(ALL_DOCS); do $(MARKDOWN_LINK_CHECK) --quiet --config .markdown_link_check_config.json $$f; done
.PHONY: install-markdown-toc
install-markdown-toc:
npm install markdown-toc
.PHONY: markdown-toc
# This target runs markdown-toc on all files that contain
# a comment <!-- tocstop -->.
#
# The recommended way to prepate a .md file for markdown-toc is
# to add these comments:
#
# <!-- Re-generate TOC with `make markdown-toc` -->
# <!-- toc -->
# <!-- tocstop -->
markdown-toc:
@for f in $(ALL_DOCS); do \
if grep -q '<!-- tocstop -->' $$f; then \
echo markdown-toc: processing $$f; \
$(MARKDOWN_TOC) --no-first-h1 -i $$f; \
else \
echo markdown-toc: no TOC markers, skipping $$f; \
fi; \
done
.PHONY: install-markdownlint .PHONY: install-markdownlint
install-markdownlint: install-markdownlint:
# TODO: Check for existence before installing npm install markdownlint-cli
npm install -g markdownlint-cli
.PHONY: markdownlint .PHONY: markdownlint
markdownlint: markdownlint:
@ -80,5 +103,5 @@ fix: table-generation misspell-correction
# Attempt to install all the tools # Attempt to install all the tools
.PHONY: install-tools .PHONY: install-tools
install-tools: install-misspell install-markdownlint install-markdown-link-check install-tools: install-misspell install-markdownlint install-markdown-link-check install-markdown-toc
@echo "All tools installed" @echo "All tools installed"

2
specification/metrics/semantic_conventions/faas-metrics.md
View File

@ -14,11 +14,13 @@ operations. By adding FaaS attributes to metric events it allows for finely tune
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` --> <!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc --> <!-- toc -->
- [Metric Instruments](#metric-instruments) - [Metric Instruments](#metric-instruments)
* [FaaS Invocations](#faas-invocations) * [FaaS Invocations](#faas-invocations)
- [Attributes](#attributes) - [Attributes](#attributes)
- [References](#references) - [References](#references)
* [Metric References](#metric-references) * [Metric References](#metric-references)
<!-- tocstop --> <!-- tocstop -->
## Metric Instruments ## Metric Instruments

2
specification/resource/semantic_conventions/README.md
View File

@ -11,6 +11,8 @@ This document defines standard attributes for resources. These attributes are ty
- [TODOs](#todos) - [TODOs](#todos)
- [Document Conventions](#document-conventions) - [Document Conventions](#document-conventions)
- [Attributes with Special Handling](#attributes-with-special-handling)
* [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable)
- [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value)
- [Service](#service) - [Service](#service)
- [Telemetry SDK](#telemetry-sdk) - [Telemetry SDK](#telemetry-sdk)

21
specification/trace/semantic_conventions/database.md
View File

@ -6,17 +6,16 @@
<!-- toc --> <!-- toc -->
- [Semantic conventions for database client calls](#semantic-conventions-for-database-client-calls) - [Connection-level attributes](#connection-level-attributes)
- [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) * [Connection-level attributes for specific technologies](#connection-level-attributes-for-specific-technologies)
- [Connection-level attributes for specific technologies](#connection-level-attributes-for-specific-technologies) - [Call-level attributes](#call-level-attributes)
- [Call-level attributes](#call-level-attributes) * [Call-level attributes for specific technologies](#call-level-attributes-for-specific-technologies)
- [Call-level attributes for specific technologies](#call-level-attributes-for-specific-technologies) + [Cassandra](#cassandra)
- [Cassandra](#cassandra) - [Examples](#examples)
- [Examples](#examples) * [MySQL](#mysql)
- [MySQL](#mysql) * [Redis](#redis)
- [Redis](#redis) * [MongoDB](#mongodb)
- [MongoDB](#mongodb)
<!-- tocstop --> <!-- tocstop -->

2
specification/trace/semantic_conventions/exceptions.md
View File

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

1
specification/trace/semantic_conventions/faas.md
View File

@ -12,6 +12,7 @@ See also the [additional instructions for instrumenting AWS Lambda](instrumentat
<!-- toc --> <!-- toc -->
- [General Attributes](#general-attributes) - [General Attributes](#general-attributes)
* [Function Name](#function-name)
* [Difference between execution and instance](#difference-between-execution-and-instance) * [Difference between execution and instance](#difference-between-execution-and-instance)
- [Incoming Invocations](#incoming-invocations) - [Incoming Invocations](#incoming-invocations)
- [Outgoing Invocations](#outgoing-invocations) - [Outgoing Invocations](#outgoing-invocations)

19
specification/trace/semantic_conventions/http.md
View File

@ -10,16 +10,15 @@ and various HTTP versions like 1.1, 2 and SPDY.
<!-- toc --> <!-- toc -->
- [Semantic conventions for HTTP spans](#semantic-conventions-for-http-spans) - [Name](#name)
- [Name](#name) - [Status](#status)
- [Status](#status) - [Common Attributes](#common-attributes)
- [Common Attributes](#common-attributes) * [HTTP request and response headers](#http-request-and-response-headers)
- [HTTP request and response headers](#http-request-and-response-headers) - [HTTP client](#http-client)
- [HTTP client](#http-client) - [HTTP server](#http-server)
- [HTTP server](#http-server) * [HTTP server definitions](#http-server-definitions)
- [HTTP server definitions](#http-server-definitions) * [HTTP Server semantic conventions](#http-server-semantic-conventions)
- [HTTP Server semantic conventions](#http-server-semantic-conventions) - [HTTP client-server example](#http-client-server-example)
- [HTTP client-server example](#http-client-server-example)
<!-- tocstop --> <!-- tocstop -->

1
specification/trace/semantic_conventions/instrumentation/aws-lambda.md
View File

@ -24,6 +24,7 @@ use cases.
* [API Gateway Request Proxy (Lambda tracing active)](#api-gateway-request-proxy-lambda-tracing-active) * [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 passive)](#sqs-lambda-tracing-passive)
* [SQS (Lambda tracing active)](#sqs-lambda-tracing-active) * [SQS (Lambda tracing active)](#sqs-lambda-tracing-active)
- [Resource Detector](#resource-detector)
<!-- tocstop --> <!-- tocstop -->

23
specification/trace/semantic_conventions/rpc.md
View File

@ -9,18 +9,17 @@ This document defines how to describe remote procedure calls
<!-- toc --> <!-- toc -->
- [Semantic conventions for RPC spans](#semantic-conventions-for-rpc-spans) - [Common remote procedure call conventions](#common-remote-procedure-call-conventions)
- [Common remote procedure call conventions](#common-remote-procedure-call-conventions) * [Span name](#span-name)
- [Span name](#span-name) * [Attributes](#attributes)
- [Attributes](#attributes) + [Service name](#service-name)
- [Service name](#service-name) * [Events](#events)
- [Events](#events) * [Distinction from HTTP spans](#distinction-from-http-spans)
- [Distinction from HTTP spans](#distinction-from-http-spans) - [gRPC](#grpc)
- [gRPC](#grpc) * [gRPC Attributes](#grpc-attributes)
- [gRPC Attributes](#grpc-attributes) * [gRPC Status](#grpc-status)
- [gRPC Status](#grpc-status) - [JSON RPC](#json-rpc)
- [JSON RPC](#json-rpc) * [JSON RPC Attributes](#json-rpc-attributes)
- [JSON RPC Attributes](#json-rpc-attributes)
<!-- tocstop --> <!-- tocstop -->

1
specification/trace/semantic_conventions/span-general.md
View File

@ -11,7 +11,6 @@ Particular operations may refer to or require some of these attributes.
<!-- toc --> <!-- toc -->
- [General network connection attributes](#general-network-connection-attributes) - [General network connection attributes](#general-network-connection-attributes)
* [`net.transport` attribute](#nettransport-attribute)
* [`net.*.name` attributes](#netname-attributes) * [`net.*.name` attributes](#netname-attributes)
- [General remote service attributes](#general-remote-service-attributes) - [General remote service attributes](#general-remote-service-attributes)
- [General identity attributes](#general-identity-attributes) - [General identity attributes](#general-identity-attributes)