diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 10f530f520b..9b84c3deefc 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,6 +1,5 @@ { "default": true, - "MD024": { "allow_different_nesting": true }, "MD029": { "style": "ordered" }, "ul-style": false, # MD004 "line-length": false, # MD013 diff --git a/specification/context/api-propagators.md b/specification/context/api-propagators.md index 1f573942450..2cdd3dfceac 100644 --- a/specification/context/api-propagators.md +++ b/specification/context/api-propagators.md @@ -13,10 +13,10 @@ Table of Contents - [Extract](#extract) - [TextMap Propagator](#textmap-propagator) - [Fields](#fields) - - [Inject](#inject-1) + - [Inject](#textmap-inject) - [Setter argument](#setter-argument) - [Set](#set) - - [Extract](#extract-1) + - [Extract](#textmap-extract) - [Getter argument](#getter-argument) - [Keys](#keys) - [Get](#get) @@ -137,7 +137,7 @@ Observe that some `Propagator`s may define, besides the returned values, additio variable names. To get a full list of fields for a specific carrier object, use the [Keys](#keys) operation. -### Inject +### TextMap Inject Injects the value into a carrier. The required arguments are the same as defined by the base [Inject](#inject) operation. @@ -167,7 +167,7 @@ Required arguments: The implementation SHOULD preserve casing (e.g. it should not transform `Content-Type` to `content-type`) if the used protocol is case insensitive, otherwise it MUST preserve casing. -### Extract +### TextMap Extract Extracts the value from an incoming request. The required arguments are the same as defined by the base [Extract](#extract) operation. @@ -249,7 +249,7 @@ Required arguments: Returns a new composite `Propagator` with the specified `Propagator`s. -### Extract +### Composite Extract Required arguments: @@ -257,7 +257,7 @@ Required arguments: - The carrier that holds propagation fields. - The instance of `Getter` invoked for each propagation key to get. -### Inject +### Composite Inject Required arguments: @@ -331,7 +331,7 @@ from both sides of request to share the same id. To maximize compatibility between OpenTelemetry and Zipkin implementations, the following guidelines have been established for B3 context propagation. -#### Extract +#### B3 Extract When extracting B3, propagators: @@ -343,7 +343,7 @@ When extracting B3, propagators: MUST set the sampled trace flag when the debug flag is set. * MUST NOT reuse `X-B3-SpanId` as the id for the server-side span. -#### Inject +#### B3 Inject When injecting B3, propagators: diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index 29fc0409c2a..2949bcb499a 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -9,7 +9,7 @@ * [Pluralization](#pluralization) - [General Metric Semantic Conventions](#general-metric-semantic-conventions) * [Instrument Naming](#instrument-naming) - * [Units](#units-1) + * [Units](#instrument-units) @@ -137,7 +137,7 @@ freely. For example, `system.paging.faults` and `system.network.packets`. Units do not need to be specified in the names since they are included during instrument creation, but can be added if there is ambiguity. -### Units +### Instrument Units Units should follow the [UCUM](http://unitsofmeasure.org/ucum.html) (need more clarification in diff --git a/specification/protocol/otlp.md b/specification/protocol/otlp.md index 00e7db36d34..1303bbf6cf3 100644 --- a/specification/protocol/otlp.md +++ b/specification/protocol/otlp.md @@ -9,22 +9,22 @@ nodes such as collectors and telemetry backends. * [Table of Contents](#table-of-contents) * [Protocol Details](#protocol-details) * [OTLP/gRPC](#otlpgrpc) - * [Concurrent Requests](#concurrent-requests) - * [Response](#response) - * [Throttling](#throttling) - * [gRPC Service and Protobuf Definitions](#grpc-service-and-protobuf-definitions) - * [Default Port](#default-port) + * [Concurrent Requests](#otlpgrpc-concurrent-requests) + * [Response](#otlpgrpc-response) + * [Throttling](#otlpgrpc-throttling) + * [gRPC Service and Protobuf Definitions](#otlpgrpc-service-and-protobuf-definitions) + * [Default Port](#otlphttp-default-port) * [OTLP/HTTP](#otlphttp) - * [Request](#request) - * [Response](#response-1) + * [Request](#otlphttp-request) + * [Response](#otlphttp-response) * [Success](#success) * [Failures](#failures) * [Bad Data](#bad-data) - * [Throttling](#throttling-1) + * [Throttling](#otlphttp-throttling) * [All Other Responses](#all-other-responses) - * [Connection](#connection) - * [Concurrent Requests](#concurrent-requests-1) - * [Default Port](#default-port-1) + * [Connection](#otlphttp-connection) + * [Concurrent Requests](#otlphttp-concurrent-requests) + * [Default Port](#otlphttp-default-port) * [Implementation Recommendations](#implementation-recommendations) * [Multi-Destination Exporting](#multi-destination-exporting) * [Known Limitations](#known-limitations) @@ -74,7 +74,7 @@ acknowledgements described in this protocol happen between a single client/server pair and do not span intermediary nodes in multi-hop delivery paths._ -#### Concurrent Requests +#### OTLP/gRPC Concurrent Requests After sending the request the client MAY wait until the response is received from the server. In that case there will be at most only one request in flight @@ -116,7 +116,7 @@ If the client is unable to deliver a certain request (e.g. a timer expired while waiting for acknowledgements) the client SHOULD record the fact that the data was not delivered. -#### Response +#### OTLP/gRPC Response The server may respond with either a success or an error to the requests. @@ -209,7 +209,7 @@ When retrying, the client SHOULD implement an exponential backoff strategy. An exception to this is the Throttling case explained below, which provides explicit instructions about retrying interval. -#### Throttling +#### OTLP/gRPC Throttling OTLP allows backpressure signalling. @@ -274,7 +274,7 @@ dependant. The server SHOULD choose a `retry_delay` value that is big enough to give the server time to recover, yet is not too big to cause the client to drop data while it is throttled. -#### gRPC Service and Protobuf Definitions +#### OTLP/gRPC Service and Protobuf Definitions gRPC service definitions [are here](https://github.com/open-telemetry/opentelemetry-proto/tree/master/opentelemetry/proto/collector). @@ -287,7 +287,7 @@ Please make sure to check the proto version and Schemas for different signals may be at different maturity level - some stable, some in beta. -#### Default Port +#### OTLP/gRPC Default Port The default network port for OTLP/gRPC is 4317. @@ -302,7 +302,7 @@ servers. Implementations MAY use HTTP/1.1 or HTTP/2 transports. Implementations that use HTTP/2 transport SHOULD fallback to HTTP/1.1 transport if HTTP/2 connection cannot be established. -#### Request +#### OTLP/HTTP Request Telemetry data is sent via HTTP POST request. The body of the POST request is a payload either in binary-encoded Protobuf format or in JSON-encoded Protobuf @@ -340,7 +340,7 @@ they are not base64-encoded like it is defined in the standard The hex encoding is used for `trace_id` and `span_id` fields in all OTLP Protobuf messages, e.g. the `Span`, `Link`, `LogRecord`, etc. messages. -#### Response +#### OTLP/HTTP Response Response body MUST be the appropriate serialized Protobuf message (see below for the specific message to use in the Success and Failure cases). @@ -398,7 +398,7 @@ that describes the bad data. The client MUST NOT retry the request when it receives `HTTP 400 Bad Request` response. -##### Throttling +##### OTLP/HTTP Throttling If the server receives more requests than the client is allowed or the server is overloaded the server SHOULD respond with `HTTP 429 Too Many Requests` or @@ -420,7 +420,7 @@ If the server disconnects without returning a response the client SHOULD retry and send the same request. The client SHOULD implement an exponential backoff strategy between retries to avoid overwhelming the server. -#### Connection +#### OTLP/HTTP Connection If the client is unable to connect to the server the client SHOULD retry the connection using exponential backoff strategy between retries. The interval @@ -437,13 +437,13 @@ Server implementations MAY accept OTLP/gRPC and OTLP/HTTP requests on the same port and multiplex the connections to the corresponding transport handler based on the "Content-Type" request header. -#### Concurrent Requests +#### OTLP/HTTP Concurrent Requests To achieve higher total throughput the client MAY send requests using several parallel HTTP connections. In that case the maximum number of parallel connections SHOULD be configurable. -#### Default Port +#### OTLP/HTTP Default Port The default network port for OTLP/HTTP is 4317.