diff --git a/Makefile b/Makefile index c87279759e6..8b896bf1044 100644 --- a/Makefile +++ b/Makefile @@ -54,7 +54,7 @@ markdown-toc: $(MARKDOWN_TOC) done $(MARKDOWN_LINT): - npm install markdownlint-cli + npm install markdownlint-cli@0.31.0 .PHONY: markdownlint markdownlint: $(MARKDOWN_LINT) diff --git a/experimental/trace/zpages.md b/experimental/trace/zpages.md index 2148f05b84f..6bfe3bf8828 100644 --- a/experimental/trace/zpages.md +++ b/experimental/trace/zpages.md @@ -56,7 +56,7 @@ Statsz is focused on metrics, as it displays metrics and measures for exported v For OpenTelemetry, a custom [span processor](../../specification/trace/sdk.md#span-processor) SHOULD be made to interface with the [Tracer API](../../specification/trace/api.md#tracer) to collect spans. This span processor collects references to running spans and exports completed spans to its own memory or to an aggregator that can aggregate information from multiple span processors. -There SHOULD be a `data aggregator` that tracks running, error, and latency buckets counts for spans grouped by their respective name. The aggregator MUST also hold some sampled spans to provide users with more information. To prevent memory overload, only some spans MUST be sampled for each bucket for each span name; for example, if that sampled span max number is set to 5, then only up to 55 pieces of span data can be kept for each span name in the aggregator (sampled_max * number of buckets = 5 * [running + error + 9 latency buckets] = 5 * 11 = 55). Aggregation work is recommended to do periodically in batches. +There SHOULD be a `data aggregator` that tracks running, error, and latency buckets counts for spans grouped by their respective name. The aggregator MUST also hold some sampled spans to provide users with more information. To prevent memory overload, only some spans MUST be sampled for each bucket for each span name; for example, if that sampled span max number is set to 5, then only up to 55 pieces of span data can be kept for each span name in the aggregator (sampled_max \* number of buckets = 5 \* [running + error + 9 latency buckets] = 5 \* 11 = 55). Aggregation work is recommended to do periodically in batches. When the user visits the Tracez endpoint, likely something similar to `host:port/tracez`, then the distribution of latencies for span names MUST be rendered. When clicking on buckets counts for a span name, additional details on individual sampled spans for that bucket MUST be shown. These details would include trace ID, parent ID, span ID, start time, attributes, and more depending on the type of bucket (running, error, or latency) and what's implemented/recorded in the other components. See [HTTP Server](#http-server) for more information on that and other implementation details. diff --git a/specification/glossary.md b/specification/glossary.md index 6d66930add5..d0fab454b15 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -195,7 +195,7 @@ Key/value pairs contained in a `Log Record`. Logs that are recorded in a format which has a well-defined structure that allows to differentiate between different elements of a Log Record (e.g. the Timestamp, -the Attributes, etc). The _Syslog protocol_ ([RFC 5424](https://tools.ietf.org/html/rfc5424)), +the Attributes, etc). The *Syslog protocol* ([RFC 5424](https://tools.ietf.org/html/rfc5424)), for example, defines a `structured-data` format. ### Flat File Logs diff --git a/specification/metrics/api.md b/specification/metrics/api.md index a0a2f248896..7a0cf166898 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -260,7 +260,7 @@ asynchronous: seconds. [Measurements](#measurement) recorded by asynchronous instruments cannot be associated with the [Context](../context/context.md). -Please note that the term _synchronous_ and _asynchronous_ have nothing to do +Please note that the term *synchronous* and *asynchronous* have nothing to do with the [asynchronous pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation). @@ -575,13 +575,13 @@ httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", schem ### Asynchronous Gauge Asynchronous Gauge is an [asynchronous Instrument](#asynchronous-instrument) -which reports non-additive value(s) (_e.g. the room temperature - it makes no -sense to report the temperature value from multiple rooms and sum them up_) when +which reports non-additive value(s) (e.g. the room temperature - it makes no +sense to report the temperature value from multiple rooms and sum them up) when the instrument is being observed. -Note: if the values are additive (_e.g. the process heap size - it makes sense +Note: if the values are additive (e.g. the process heap size - it makes sense to report the heap size from multiple processes and sum them up, so we get the -total heap usage_), use [Asynchronous Counter](#asynchronous-counter) or +total heap usage), use [Asynchronous Counter](#asynchronous-counter) or [Asynchronous UpDownCounter](#asynchronous-updowncounter). Example uses for Asynchronous Gauge: @@ -845,9 +845,9 @@ customersInStore.Add(-1, new Account { Type = "residential" }); ### Asynchronous UpDownCounter Asynchronous UpDownCounter is an [asynchronous -Instrument](#asynchronous-instrument) which reports additive value(s) (_e.g. the +Instrument](#asynchronous-instrument) which reports additive value(s) (e.g. the process heap size - it makes sense to report the heap size from multiple -processes and sum them up, so we get the total heap usage_) when the instrument +processes and sum them up, so we get the total heap usage) when the instrument is being observed. Note: if the value is diff --git a/specification/metrics/datamodel.md b/specification/metrics/datamodel.md index ea99ae2ba81..cc70ec0923c 100644 --- a/specification/metrics/datamodel.md +++ b/specification/metrics/datamodel.md @@ -270,9 +270,9 @@ characteristics for a Timeseries. A metric stream is identified by: It is possible (and likely) that more than one metric stream is created per `Instrument` in the event model. -__Note: The same `Resource`, `name` and `Attribute`s but differing point kind +**Note: The same `Resource`, `name` and `Attribute`s but differing point kind coming out of an OpenTelemetry SDK is considered an "error state" that SHOULD -be handled by an SDK.__ +be handled by an SDK.** A metric stream can use one of these basic point kinds, all of which satisfy the requirements above, meaning they define a decomposable @@ -599,7 +599,7 @@ reference implementations. ##### Scale Zero: Extract the Exponent For scale zero, the index of a value equals its normalized base-2 -exponent, meaning the value of _exponent_ in the base-2 fractional +exponent, meaning the value of *exponent* in the base-2 fractional representation `1._significand_ * 2**_exponent_`. Normal IEEE 754 double-width floating point values have indices in the range `[-1022, +1023]` and subnormal values have indices in the range @@ -754,7 +754,7 @@ originating source of truth. In practical terms, this implies the following: identified in some way. - Aggregations of metric streams MUST only be written from a single logical source. - __Note: This implies aggregated metric streams must reach one destination__. + **Note: This implies aggregated metric streams must reach one destination**. In systems, there is the possibility of multiple writers sending data for the same metric stream (duplication). For example, if an SDK implementation fails diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index df8a5de8f0b..1122b3df6f0 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -548,7 +548,7 @@ By default, explicit bucket histogram aggregation with more than 1 bucket will use `AlignedHistogramBucketExemplarReservoir`. All other aggregations will use `SimpleFixedSizeExemplarReservoir`. -*SimpleExemplarReservoir* +_SimpleExemplarReservoir_ This Exemplar reservoir MAY take a configuration parameter for the size of the reservoir pool. The reservoir will accept measurements using an equivalent of the [naive reservoir sampling @@ -564,7 +564,7 @@ algorithm](https://en.wikipedia.org/wiki/Reservoir_sampling) Additionally, the `num_measurements_seen` count SHOULD be reset at every collection cycle. -*AlignedHistogramBucketExemplarReservoir* +_AlignedHistogramBucketExemplarReservoir_ This Exemplar reservoir MUST take a configuration parameter that is the configuration of a Histogram. This implementation MUST keep the last seen measurement that falls within a histogram bucket. The reservoir will accept diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index f664e97b95e..26c9f708036 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -96,7 +96,7 @@ path. * `http.scheme`, `net.peer.ip`, `net.peer.port`, `http.target` **[2]** For server metric attributes, `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. ). -It is thus preferred to supply the raw data that *is* available. +It is thus preferred to supply the raw data that _is_ available. Namely, one of the following sets is RECOMMENDED (in order of usual preference unless for a particular web server/framework it is known that some other set is preferable for some reason; all strings must be non-empty): * `http.scheme`, `http.host`, `http.target` diff --git a/specification/schemas/overview.md b/specification/schemas/overview.md index e97586d5fe6..727593997a6 100644 --- a/specification/schemas/overview.md +++ b/specification/schemas/overview.md @@ -239,9 +239,9 @@ field in the messages: - The schema_url field in the InstrumentationLibraryLogs message applies to the contained LogRecord messages. -- If schema_url field is non-empty both in Resource* message and in the - contained InstrumentationLibrary* message then the value in - InstrumentationLibrary* message takes the precedence. +- If schema_url field is non-empty both in Resource\*message and in the + contained InstrumentationLibrary\* message then the value in + InstrumentationLibrary\* message takes the precedence. ## API Support diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index bf48cf99cd6..17a985f0ad6 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -151,7 +151,7 @@ usage in Zipkin Exporter configuration: This will be used to specify whether or not the exporter uses v1 or v2, json, thrift or protobuf. As of 1.0 of the specification, there -*is no specified default, or configuration via environment variables*. +_is no specified default, or configuration via environment variables_. ## Prometheus Exporter diff --git a/specification/trace/api.md b/specification/trace/api.md index fb54ee5654c..246da6b125d 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -286,11 +286,11 @@ the entire operation and, optionally, one or more sub-spans for its sub-operatio - A list of timestamped [`Event`s](#add-events) - A [`Status`](#set-status). -The _span name_ concisely identifies the work represented by the Span, +The *span name* concisely identifies the work represented by the Span, for example, an RPC method name, a function name, or the name of a subtask or stage within a larger computation. The span name SHOULD be the most general string that identifies a -(statistically) interesting _class of Spans_, +(statistically) interesting *class of Spans*, rather than individual Span instances while still being human-readable. That is, "get_user" is a reasonable name, while "get_user/314159", where "314159" is a user ID, is not a good name due to its high cardinality. @@ -374,14 +374,14 @@ The API MUST accept the following parameters: Each span has zero or one parent span and zero or more child spans, which represent causally related operations. A tree of related spans comprises a -trace. A span is said to be a _root span_ if it does not have a parent. Each +trace. A span is said to be a *root span* if it does not have a parent. Each trace includes a single root span, which is the shared ancestor of all other spans in the trace. Implementations MUST provide an option to create a `Span` as a root span, and MUST generate a new `TraceId` for each root span created. For a Span with a parent, the `TraceId` MUST be the same as the parent. Also, the child span MUST inherit all `TraceState` values of its parent by default. -A `Span` is said to have a _remote parent_ if it is the child of a `Span` +A `Span` is said to have a *remote parent* if it is the child of a `Span` created in another process. Each propagators' deserialization must set `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the parent is remote. diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 706564f680e..4ff7df04d9e 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -28,7 +28,7 @@ HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). Many REST APIs encode parameters into URI path, e.g. `/api/users/123` where `123` is a user id, which creates high cardinality value space not suitable for span names. In case of HTTP servers, these endpoints are often mapped by the server -frameworks to more concise _HTTP routes_, e.g. `/api/users/{user_id}`, which are +frameworks to more concise *HTTP routes*, e.g. `/api/users/{user_id}`, which are recommended as the low cardinality span names. However, the same approach usually does not work for HTTP client spans, especially when instrumentation is provided by a lower-level middleware that is not aware of the specifics of how the URIs diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 40861138abc..b5a518b20a1 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -178,7 +178,7 @@ For message consumers, the following additional attributes may be set: | `process` | process | -The _receive_ span is be used to track the time used for receiving the message(s), whereas the _process_ span(s) track the time for processing the message(s). +The *receive* span is be used to track the time used for receiving the message(s), whereas the *process* span(s) track the time for processing the message(s). Note that one or multiple Spans with `messaging.operation` = `process` may often be the children of a Span with `messaging.operation` = `receive`. The distinction between receiving and processing of messages is not always of particular interest or sometimes hidden away in a framework (see the [Message consumption](#message-consumption) section above) and therefore the attribute can be left out. For batch receiving and processing (see the [Batch receiving](#batch-receiving) and [Batch processing](#batch-processing) examples below) in particular, the attribute SHOULD be set. @@ -189,7 +189,7 @@ Instead span kind should be set to either `CONSUMER` or `SERVER` according to th #### RabbitMQ -In RabbitMQ, the destination is defined by an _exchange_ and a _routing key_. +In RabbitMQ, the destination is defined by an *exchange* and a *routing key*. `messaging.destination` MUST be set to the name of the exchange. This will be an empty string if the default exchange is used.