diff --git a/semantic_conventions/trace/exception.yaml b/semantic_conventions/trace/exception.yaml index 29573771030..61f0296e415 100644 --- a/semantic_conventions/trace/exception.yaml +++ b/semantic_conventions/trace/exception.yaml @@ -42,7 +42,7 @@ groups: whether it will escape the scope of a span. However, it is trivial to know that an exception will escape, if one checks for an active exception just before ending the span, - as done in the [example above](#exception-end-example). + as done in the [example above](#recording-an-exception). It follows that an exception may still escape the scope of the span even if the `exception.escaped` attribute was not set or set to false, diff --git a/specification/common/common.md b/specification/common/common.md index 80a13012f44..774c2361302 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -9,6 +9,7 @@ - [Attribute](#attribute) * [Attribute Limits](#attribute-limits) + + [Configurable Parameters](#configurable-parameters) + [Exempt Entities](#exempt-entities) - [Attribute Collections](#attribute-collections) @@ -57,7 +58,7 @@ limits placed on attributes, they can quickly exhaust available memory, resultin in crashes that are difficult to recover from safely. By default an SDK SHOULD apply truncation as per the list of -[configurable parameters](#attribute-limits-configuration) below. +[configurable parameters](#configurable-parameters) below. If an SDK provides a way to: @@ -88,8 +89,7 @@ it isn't set, then the SDK MUST attempt to use the general limit. If neither are defined, then the SDK MUST try to use the model-specific limit default value, followed by the global limit default value. - -**Configurable parameters:** +#### Configurable Parameters * `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record; * `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length; diff --git a/specification/glossary.md b/specification/glossary.md index c530ab99874..30dde00b739 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -83,9 +83,6 @@ An ABI (application binary interface) is an interface which defines interactions ABI compatibility is important for some languages, especially those which provide a form of machine code. For other languages, ABI compatibility may not be a relevant requirement. - - - ### In-band and Out-of-band Data > In telecommunications, **in-band signaling** is the sending of control information within the same band or channel used for data such as voice or video. This is in contrast to **out-of-band signaling** which is sent over a different channel, or even over a separate network ([Wikipedia](https://en.wikipedia.org/wiki/In-band_signaling)). diff --git a/specification/metrics/datamodel.md b/specification/metrics/datamodel.md index 7791cbadfa1..5e986c8f374 100644 --- a/specification/metrics/datamodel.md +++ b/specification/metrics/datamodel.md @@ -369,7 +369,7 @@ to the end user, although this subject deserves attention. A metric stream can use one of these basic point kinds, all of which satisfy the requirements above, meaning they define a decomposable aggregate function (also known as a “natural merge” function) for points of the -same kind. [1](#otlpdatapointfn) +same kind. [1](#footnotes) The basic point kinds are: @@ -1318,6 +1318,5 @@ To convert OTLP resource attributes to Prometheus labels, string Attribute value ## Footnotes -[1]: OTLP supports data point kinds that do not -satisfy these conditions; they are well-defined but do not support standard -metric data transformations. +\[1\] OTLP supports data point kinds that do not satisfy these conditions; they are +well-defined but do not support standard metric data transformations. diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index f264c175bb4..bcfdab38958 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -94,7 +94,7 @@ For client-side metrics `net.peer.port` is required if the connection is IP-base For server-side spans `net.peer.port` is optional (it describes the port the client is connecting from). Furthermore, setting [net.transport][] is required for non-IP connection like named pipe bindings. -[net.transport]: ../../trace/semantic_conventions/span-general.md#nettransport-attribute +[net.transport]: ../../trace/semantic_conventions/span-general.md#network-transport-attributes ### Service name diff --git a/specification/metrics/semantic_conventions/system-metrics.md b/specification/metrics/semantic_conventions/system-metrics.md index 11b97442e6d..5ac42f2cb80 100644 --- a/specification/metrics/semantic_conventions/system-metrics.md +++ b/specification/metrics/semantic_conventions/system-metrics.md @@ -66,13 +66,13 @@ memory](#systempaging---pagingswap-metrics). | | | | | | direction | read, write | | system.disk.operations | | {operations} | Asynchronous Counter | Int64 | device | (identifier) | | | | | | | direction | read, write | -| system.disk.io_time[1](#io_time) | Time disk spent activated | s | Asynchronous Counter | Double | device | (identifier) | -| system.disk.operation_time[2](#operation_time) | Sum of the time each operation took to complete | s | Asynchronous Counter | Double | device | (identifier) | +| system.disk.io_time\[1\] | Time disk spent activated | s | Asynchronous Counter | Double | device | (identifier) | +| system.disk.operation_time\[2\] | Sum of the time each operation took to complete | s | Asynchronous Counter | Double | device | (identifier) | | | | | | | direction | read, write | | system.disk.merged | | {operations} | Asynchronous Counter | Int64 | device | (identifier) | | | | | | | direction | read, write | -1 The real elapsed time ("wall clock") +1 The real elapsed time ("wall clock") used in the I/O path (time from operations running in parallel are not counted). Measured as: @@ -82,7 +82,7 @@ counted). Measured as: Time"](https://docs.microsoft.com/en-us/archive/blogs/askcore/windows-performance-monitor-disk-counters-explained#windows-performance-monitor-disk-counters-explained:~:text=%25%20Idle%20Time,Idle\)%20to%200%20(meaning%20always%20busy).) performance counter: `uptime * (100 - "Disk\% Idle Time") / 100` -2 Because it is the sum of time each +2 Because it is the sum of time each request took, parallel-issued requests each contribute to make the count grow. Measured as: @@ -112,11 +112,11 @@ perf counter (similar for Writes) **Description:** System level network metrics. | Name | Description | Units | Instrument Type | Value Type | Attribute Key | Attribute Values | | ---------------------------------------------- | ----------------------------------------------------------------------------- | ------------- | -------------------------- | ---------- | ------------- | ---------------------------------------------------------------------------------------------- | -| system.network.dropped[1](#dropped) | Count of packets that are dropped or discarded even though there was no error | {packets} | Asynchronous Counter | Int64 | device | (identifier) | +| system.network.dropped\[1\] | Count of packets that are dropped or discarded even though there was no error | {packets} | Asynchronous Counter | Int64 | device | (identifier) | | | | | | | direction | transmit, receive | | system.network.packets | | {packets} | Asynchronous Counter | Int64 | device | (identifier) | | | | | | | direction | transmit, receive | -| system.network.errors[2](#errors) | Count of network errors detected | {errors} | Asynchronous Counter | Int64 | device | (identifier) | +| system.network.errors\[2\] | Count of network errors detected | {errors} | Asynchronous Counter | Int64 | device | (identifier) | | | | | | | direction | transmit, receive | | system.network.io | | By | Asynchronous Counter | Int64 | device | (identifier) | | | | | | | direction | transmit, receive | @@ -124,7 +124,7 @@ perf counter (similar for Writes) | | | | | | protocol | tcp, udp, [etc.](https://en.wikipedia.org/wiki/Transport_layer#Protocols) | | | | | | | state | [e.g. for tcp](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Protocol_operation) | -1 Measured as: +1 Measured as: - Linux: the `drop` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). @@ -133,7 +133,7 @@ perf counter (similar for Writes) from [`GetIfEntry2`](https://docs.microsoft.com/en-us/windows/win32/api/netioapi/nf-netioapi-getifentry2). -2 Measured as: +2 Measured as: - Linux: the `errs` column in `/proc/dev/net` ([source](https://web.archive.org/web/20180321091318/http://www.onlamp.com/pub/a/linux/2000/11/16/LinuxAdmin.html)). diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 0083d7b9b34..6a184135082 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -8,7 +8,7 @@ This document specifies the configuration options available to the OpenTelemetry The following configuration options MUST be available to configure the OTLP exporter. Each configuration option MUST be overridable by a signal specific option. -- **Endpoint (OTLP/HTTP)**: Target URL to which the exporter is going to send spans or metrics. The endpoint MUST be a valid URL with scheme (http or https) and host, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). A scheme of https indicates a secure connection. When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as [described below](#per-signal-urls). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details. +- **Endpoint (OTLP/HTTP)**: Target URL to which the exporter is going to send spans or metrics. The endpoint MUST be a valid URL with scheme (http or https) and host, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). A scheme of https indicates a secure connection. When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as [described below](#endpoint-urls-for-otlphttp). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details. - Default: `http://localhost:4318` [1] - Env vars: `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` @@ -68,8 +68,6 @@ Supported values for `OTEL_EXPORTER_OTLP_*COMPRESSION` options: - `none` if compression is disabled. - `gzip` is the only specified compression method for now. - - ### Endpoint URLs for OTLP/HTTP Based on the environment variables above, the OTLP/HTTP exporter MUST construct URLs diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index dc2a66d3a66..a1b30ca5071 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -101,7 +101,7 @@ See the SDK [Attribute Limits](common/common.md#attribute-limits) section for th | OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. | | OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | | -## Span Limits +## Span Limits **Status**: [Stable](document-status.md) diff --git a/specification/trace/api.md b/specification/trace/api.md index 7a1b9a7aeed..58c68c970d6 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -273,7 +273,6 @@ A `Span` represents a single operation within a trace. Spans can be nested to form a trace tree. Each trace contains a root span, which typically describes the entire operation and, optionally, one or more sub-spans for its sub-operations. - `Span`s encapsulate: - The span name diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index a9a09534695..7cc6dd9f292 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -13,6 +13,7 @@ * [ForceFlush](#forceflush) - [Additional Span Interfaces](#additional-span-interfaces) - [Sampling](#sampling) + * [Recording Sampled reaction table](#recording-sampled-reaction-table) * [SDK Span creation](#sdk-span-creation) * [Sampler](#sampler) + [ShouldSample](#shouldsample) @@ -118,7 +119,7 @@ Thus, the SDK specification defines sets of possible requirements for * **Readable span**: A function receiving this as argument MUST be able to access all information that was added to the span, as listed - [in the API spec](api.md#span-data-members). In particular, it MUST also be + [in the API spec](api.md#span). In particular, it MUST also be able to access the `InstrumentationScope` [since 1.10.0] and `Resource` information (implicitly) associated with the span. For backwards compatibility it MUST also be able to access the `InstrumentationLibrary` @@ -187,7 +188,7 @@ The flag combination `SampledFlag == true` and `IsRecording == false` could cause gaps in the distributed trace, and because of this OpenTelemetry API MUST NOT allow this combination. - +### Recording Sampled reaction table The following table summarizes the expected behavior for each combination of `IsRecording` and `SampledFlag`. @@ -404,7 +405,7 @@ public final class SpanLimits { **Configurable parameters:** -* [all common options applicable to attributes](../common/common.md#attribute-limits-configuration) +* [all common options applicable to attributes](../common/common.md#configurable-parameters) * `EventCountLimit` (Default=128) - Maximum allowed span event count; * `LinkCountLimit` (Default=128) - Maximum allowed span link count; * `AttributePerEventCountLimit` (Default=128) - Maximum allowed attribute per span event count; diff --git a/specification/trace/semantic_conventions/exceptions.md b/specification/trace/semantic_conventions/exceptions.md index 81f92075dd0..916b372f7d9 100644 --- a/specification/trace/semantic_conventions/exceptions.md +++ b/specification/trace/semantic_conventions/exceptions.md @@ -18,8 +18,6 @@ exceptions. An exception SHOULD be recorded as an `Event` on the span during which it occurred. The name of the event MUST be `"exception"`. - - A typical template for an auto-instrumentation implementing this semantic convention using an [API-provided `recordException` method](../api.md#record-exception) could look like this (pseudo-Java): @@ -61,7 +59,7 @@ It is usually not possible to determine at the point where an exception is throw whether it will escape the scope of a span. However, it is trivial to know that an exception will escape, if one checks for an active exception just before ending the span, -as done in the [example above](#exception-end-example). +as done in the [example above](#recording-an-exception). It follows that an exception may still escape the scope of the span even if the `exception.escaped` attribute was not set or set to false, diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index b5a518b20a1..0abaf12d56d 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -159,7 +159,7 @@ Furthermore, it is strongly recommended to add the [`net.transport`][] attribute These attributes should be set to the broker to which the message is sent/from which it is received. [network attributes]: span-general.md#general-network-connection-attributes -[`net.transport`]: span-general.md#nettransport-attribute +[`net.transport`]: span-general.md#network-transport-attributes [Hangfire]: https://www.hangfire.io/ For message consumers, the following additional attributes may be set: diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index d06db4d51a0..1f99f6d0050 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -98,7 +98,7 @@ In this example, spans representing client request should have their `peer.servi Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. [network attributes]: span-general.md#general-network-connection-attributes -[net.transport]: span-general.md#nettransport-attribute +[net.transport]: span-general.md#network-transport-attributes [`service.name`]: ../../resource/semantic_conventions/README.md#service [`peer.service`]: span-general.md#general-remote-service-attributes diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 9bad0c5a5e4..df25818b207 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -11,6 +11,7 @@ Particular operations may refer to or require some of these attributes. - [General network connection attributes](#general-network-connection-attributes) + * [Network transport attributes](#network-transport-attributes) * [`net.*.name` attributes](#netname-attributes) - [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes) @@ -28,7 +29,7 @@ while the `net.host.*` properties describe the local end. In an ideal situation, not accounting for proxies, multiple IP addresses or host names, the `net.peer.*` properties of a client are equal to the `net.host.*` properties of the server and vice versa. - +### Network transport attributes | Attribute | Type | Description | Examples | Required | @@ -100,8 +101,6 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `net.peer.name` is the only attribute that usually makes sense (see description of `net.peer.name` below). - - ### `net.*.name` attributes For IP-based communication, the name should be a DNS host name.