From b6bd1f113fc20456a421f699ea4692a2689b0333 Mon Sep 17 00:00:00 2001 From: James Thompson Date: Sun, 23 Nov 2025 16:53:04 +1100 Subject: [PATCH 1/2] Run linting using latest linter --- .markdownlint.yaml | 2 + Makefile | 2 +- oteps/0119-standard-system-metrics.md | 6 + ...-elastic-common-schema-in-opentelemetry.md | 4 +- oteps/0258-env-context-baggage-carriers.md | 5 +- ...ng-attributes-to-support-complex-values.md | 22 +-- oteps/README.md | 3 - oteps/entities/0264-resource-and-entities.md | 8 +- oteps/logs/0097-log-data-model.md | 144 +++++++++--------- oteps/metrics/0003-measure-metric-type.md | 14 +- ...-metric-instrument-optional-refinements.md | 68 ++++----- .../0098-metric-instruments-explained.md | 12 +- .../0146-metrics-prototype-scenarios.md | 1 + oteps/trace/0168-sampling-propagation.md | 24 +-- ...ing-semantic-conventions-span-structure.md | 26 ++-- .../4673-experimental-probability-sampling.md | 3 + specification/common/mapping-to-non-otlp.md | 16 +- .../sdk-environment-variables.md | 1 - specification/document-status.md | 20 +-- specification/entities/data-model.md | 10 +- specification/logs/data-model-appendix.md | 30 ++-- specification/logs/data-model.md | 96 ++++++------ specification/metrics/sdk.md | 16 +- specification/profiles/README.md | 4 +- specification/resource/data-model.md | 6 +- specification/trace/api.md | 10 +- specification/trace/sdk.md | 18 +-- specification/trace/sdk_exporters/zipkin.md | 46 +++--- .../trace/tracestate-probability-sampling.md | 6 +- 29 files changed, 315 insertions(+), 308 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index a361c8f1b32..0c53819b722 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -14,3 +14,5 @@ no-inline-html: false fenced-code-language: false no-duplicate-heading: false descriptive-link-text: false +first-line-h1: false +no-alt-text: false diff --git a/Makefile b/Makefile index a9f87d56e13..87e8465e8d3 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ # All documents to be used in spell check. -ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' -not -path '*semantic_conventions*' | sort) +ALL_DOCS := $(shell find . -type f -name '*.md' -not -path './.github/*' -not -path './node_modules/*' -not -path '*semantic_conventions*' -not -name 'spec-compliance-matrix.md' | sort) PWD := $(shell pwd) TOOLS_DIR := ./internal/tools diff --git a/oteps/0119-standard-system-metrics.md b/oteps/0119-standard-system-metrics.md index 4ca2e3f2887..af502feffda 100644 --- a/oteps/0119-standard-system-metrics.md +++ b/oteps/0119-standard-system-metrics.md @@ -57,6 +57,7 @@ In the tables below, units of `1` refer to a ratio value that is always in the r #### `system.cpu.` **Description:** System level processor metrics. + |Name |Units |Instrument Type |Value Type|Label Key|Label Values | |----------------------|-------|-----------------|----------|---------|-----------------------------------| |system.cpu.time |seconds|SumObserver |Double |state |idle, user, system, interrupt, etc.| @@ -67,6 +68,7 @@ In the tables below, units of `1` refer to a ratio value that is always in the r #### `system.memory.` **Description:** System level memory metrics. + |Name |Units|Instrument Type |Value Type|Label Key|Label Values | |-------------------------|-----|-----------------|----------|---------|------------------------| |system.memory.usage |bytes|UpDownSumObserver|Int64 |state |used, free, cached, etc.| @@ -75,6 +77,7 @@ In the tables below, units of `1` refer to a ratio value that is always in the r #### `system.swap.` **Description:** System level swap/paging metrics. + |Name |Units |Instrument Type |Value Type|Label Key|Label Values| |----------------------------|----------|-----------------|----------|---------|------------| |system.swap.usage |pages |UpDownSumObserver|Int64 |state |used, free | @@ -86,6 +89,7 @@ In the tables below, units of `1` refer to a ratio value that is always in the r #### `system.disk.` **Description:** System level disk performance metrics. + |Name |Units |Instrument Type|Value Type|Label Key|Label Values| |----------------------------|----------|---------------|----------|---------|------------| |system.disk.io|bytes |SumObserver |Int64 |device |(identifier)| @@ -100,6 +104,7 @@ In the tables below, units of `1` refer to a ratio value that is always in the r #### `system.filesystem.` **Description:** System level filesystem metrics. + |Name |Units|Instrument Type |Value Type|Label Key|Label Values | |-----------------------------|-----|-----------------|----------|---------|--------------------| |system.filesystem.usage |bytes|UpDownSumObserver|Int64 |device |(identifier) | @@ -110,6 +115,7 @@ In the tables below, units of `1` refer to a ratio value that is always in the r #### `system.network.` **Description:** System level network metrics. + |Name |Units |Instrument Type |Value Type|Label Key|Label Values | |-------------------------------|-----------|-----------------|----------|---------|----------------------------------------------------------------------------------------------| |system.network.dropped\_packets|packets |SumObserver |Int64 |device |(identifier) | diff --git a/oteps/0199-support-elastic-common-schema-in-opentelemetry.md b/oteps/0199-support-elastic-common-schema-in-opentelemetry.md index 930b78f1388..e497e8009d5 100644 --- a/oteps/0199-support-elastic-common-schema-in-opentelemetry.md +++ b/oteps/0199-support-elastic-common-schema-in-opentelemetry.md @@ -148,7 +148,7 @@ Example of a Nginx Access Log entry structured with ECS ## Principles | Description | [OTel Logs and Event Record](../specification/logs/data-model.md#log-and-event-record-definition) | [Elastic Common Schema (ECS)](https://www.elastic.co/docs/reference/ecs) | -|-------------|-------------|--------| +| ----------- | ------------- | -------- | | Metadata shared by all the Log Messages / Spans / Metrics of an application instance | Resource Attributes | ECS fields | | Metadata specific to each Log Message / Span / Metric data point | Attributes | ECS Fields | | Message of log events | Body | [message field](https://www.elastic.co/docs/reference/ecs/ecs-base#field-message) | @@ -159,7 +159,7 @@ Example of a Nginx Access Log entry structured with ECS ## Data Types | Category | OTel Logs and Event Record (all or a subset of GRPC data types) | ECS Data Types | -|---|---|---| +| --- | --- | --- | | Text | string | text, match_only_text, keyword constant_keyword, wildcard | | Dates | uint64 nanoseconds since Unix epoch | date, date_nanos | | Numbers | number | long, double, scaled_float, boolean… | diff --git a/oteps/0258-env-context-baggage-carriers.md b/oteps/0258-env-context-baggage-carriers.md index 56736afb5a8..5f5a2cf16d7 100644 --- a/oteps/0258-env-context-baggage-carriers.md +++ b/oteps/0258-env-context-baggage-carriers.md @@ -145,7 +145,6 @@ Defining the specification for Environment Variables as carriers will have a wide impact to the industry in enabling better observability to systems outside of the normal HTTP microservice architecture. -[w3c-bag]: https://www.w3.org/TR/baggage/#header-name [bag-api]: https://opentelemetry.io/docs/specs/otel/baggage/api/ The above prototype example came from the resources mentioned in [this @@ -280,9 +279,9 @@ mentioned in [opentelemetry-specification #740](https://github.com/open-telemetr * [hotel-california](https://github.com/parsonsmatt/hotel-california/issues/3) Additionally, there was a prototype implementation for environment variables as -context carriers written in the [Python SDK][python-env]. +context carriers written in the [Python SDK][python-sdkenv]. -[python-env]: https://github.com/open-telemetry/opentelemetry-specification/issues/740#issuecomment-919657003 +[python-sdkenv]: https://github.com/open-telemetry/opentelemetry-specification/issues/740#issuecomment-919657003 ## Alternatives and why they were not chosen diff --git a/oteps/4485-extending-attributes-to-support-complex-values.md b/oteps/4485-extending-attributes-to-support-complex-values.md index dc361744792..7ca2d0bd7fd 100644 --- a/oteps/4485-extending-attributes-to-support-complex-values.md +++ b/oteps/4485-extending-attributes-to-support-complex-values.md @@ -295,18 +295,18 @@ This approach reduces performance overhead and the volume of transmitted data an See [the gist](https://gist.github.com/lmolkova/737ebba190b206a5d60bbc075fea538b) for additional details. -| Backend | Handles complex attributes gracefully? | Comments | -| --------------------------------- | ----- | ------------------------------ | -| Jaeger (OTLP) | :white_check_mark: | serializes to JSON string | +| Backend | Handles complex attributes gracefully? | Comments | +| ------- | -------------------------------------- | -------- | +| Jaeger (OTLP) | :white_check_mark: | serializes to JSON string | | Prometheus with OTLP remote write | :white_check_mark: | serializes to JSON string | -| Grafana Tempo (OTLP) | :white_check_mark: | serializes to JSON string, viewable but can't query using this attribute | -| Grafana Loki (OTLP) | :white_check_mark: | flattens | -| Aspire dashboard (OTLP) | :white_check_mark: | serializes to JSON string | -| ClickHouse (collector exporter) | :white_check_mark: | serializes to JSON string, can parse JSON and query | -| Honeycomb (OTLP) | :white_check_mark: | flattens if less than 5 layers deep, not array or binary data, JSON string otherwise | -| Logfire (OTLP) | :white_check_mark: | stored as JSON, native support for JSON in queries | -| New Relic (OTLP) | :white_check_mark: | drops the complex attribute | | -| Splunk (OTLP and HEC exporter) | :white_check_mark: | flattens for logs (HEC), serializes to JSON string for traces and metrics (OTLP) | +| Grafana Tempo (OTLP) | :white_check_mark: | serializes to JSON string, viewable but can't query using this attribute | +| Grafana Loki (OTLP) | :white_check_mark: | flattens | +| Aspire dashboard (OTLP) | :white_check_mark: | serializes to JSON string | +| ClickHouse (collector exporter) | :white_check_mark: | serializes to JSON string, can parse JSON and query | +| Honeycomb (OTLP) | :white_check_mark: | flattens if less than 5 layers deep, not array or binary data, JSON string otherwise | +| Logfire (OTLP) | :white_check_mark: | stored as JSON, native support for JSON in queries | +| New Relic (OTLP) | :white_check_mark: | drops the complex attribute | +| Splunk (OTLP and HEC exporter) | :white_check_mark: | flattens for logs (HEC), serializes to JSON string for traces and metrics (OTLP) | > [!NOTE] > This list only reflects the behavior at the time of writing and may change in the future. diff --git a/oteps/README.md b/oteps/README.md index f509c631ed6..2ddc38f3071 100644 --- a/oteps/README.md +++ b/oteps/README.md @@ -88,6 +88,3 @@ Have suggestions? Concerns? Questions? **Please** raise an issue or raise the ma ## Background on the OpenTelemetry OTEP process Our OTEP process borrows from the [Rust RFC](https://github.com/rust-lang/rfcs) and [Kubernetes Enhancement Proposal](https://github.com/kubernetes/enhancements) processes, the former also being [very influential](https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/0000-kep-process/README.md#prior-art) on the latter; as well as the [OpenTracing OTEP](https://github.com/opentracing/specification/blob/master/rfc_process.md) process. Massive kudos and thanks to the respective authors and communities for providing excellent prior art 💖 - -[slack-image]: https://img.shields.io/badge/Slack-4A154B?style=for-the-badge&logo=slack&logoColor=white -[slack-url]: https://cloud-native.slack.com/archives/C01N7PP1THC diff --git a/oteps/entities/0264-resource-and-entities.md b/oteps/entities/0264-resource-and-entities.md index 0c66d95c348..ab4eefd6f62 100644 --- a/oteps/entities/0264-resource-and-entities.md +++ b/oteps/entities/0264-resource-and-entities.md @@ -206,8 +206,8 @@ The following changes are made: | Field | Type | Description | Changes | | ----- | ---- | ----------- | ------- | | schema_url | string | The Schema URL, if known. This is the identifier of the Schema that the resource data is recorded in. This field is deprecated and should no longer be used. | Will be deprecated | -| dropped_attributes_count | integer | dropped_attributes_count is the number of dropped attributes. If the value is 0, then no attributes were dropped. | Unchanged | -| attributes | repeated KeyValue | Set of attributes that describe the resource.

Attribute keys MUST be unique (it is not allowed to have more than one attribute with the same key).| Unchanged | +| dropped_attributes_count | integer | dropped_attributes_count is the number of dropped attributes. If the value is 0, then no attributes were dropped. | Unchanged | +| attributes | repeated KeyValue | Set of attributes that describe the resource.

Attribute keys MUST be unique (it is not allowed to have more than one attribute with the same key). | Unchanged | | entities | repeated ResourceEntityRef | Set of entities that participate in this Resource. | Added | The DataModel would ensure that attributes in Resource are produced from both the identifying and descriptive attributes of Entity. This does not mean the protocol needs to transmit duplicate data, that design is TBD. @@ -220,8 +220,8 @@ The entityref data model, would have the following changes from the original [en | ----- | ---- | ----------- | ------- | | schema_url | string | The Schema URL, if known. This is the identifier of the Schema that the entity data is recorded in. To learn more about Schema URL ([see docs](https://opentelemetry.io/docs/specs/otel/schemas/#schema-url)) | added | | type | string | Defines the type of the entity. MUST not change during the lifetime of the entity. For example: "service" or "host". This field is required and MUST not be empty for valid entities. | unchanged | -| identifying_attributes_keys | repeated string | Attribute Keys that identify the entity.
MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

These keys MUST exists in Resource.attributes.

Follows OpenTelemetry common attribute definition. SHOULD follow OpenTelemetry semantic conventions for attributes.| now a reference | -| descriptive_attributes_keys | repeated string | Descriptive (non-identifying) attribute keys of the entity.
MAY change over the lifetime of the entity. MAY be empty. These attribute keys are not part of entity's identity.

These keys MUST exist in Resource.attributes.

Follows any value definition in the OpenTelemetry spec - it can be a scalar value, byte array, an array or map of values. Arbitrary deep nesting of values for arrays and maps is allowed.

SHOULD follow OpenTelemetry semantic conventions for attributes.| now a reference | +| identifying_attributes_keys | repeated string | Attribute Keys that identify the entity.
MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

These keys MUST exists in Resource.attributes.

Follows OpenTelemetry common attribute definition. SHOULD follow OpenTelemetry semantic conventions for attributes. | now a reference | +| descriptive_attributes_keys | repeated string | Descriptive (non-identifying) attribute keys of the entity.
MAY change over the lifetime of the entity. MAY be empty. These attribute keys are not part of entity's identity.

These keys MUST exist in Resource.attributes.

Follows any value definition in the OpenTelemetry spec - it can be a scalar value, byte array, an array or map of values. Arbitrary deep nesting of values for arrays and maps is allowed.

SHOULD follow OpenTelemetry semantic conventions for attributes. | now a reference | ### Resource Identity diff --git a/oteps/logs/0097-log-data-model.md b/oteps/logs/0097-log-data-model.md index a5936524ac0..b1c7e3b8b4d 100644 --- a/oteps/logs/0097-log-data-model.md +++ b/oteps/logs/0097-log-data-model.md @@ -164,18 +164,18 @@ about the meaning of the field reviewing the examples may be helpful. Here is the list of fields in a log record: -Field Name |Description ----------------|-------------------------------------------- -Timestamp |Time when the event occurred. -TraceId |Request trace id. -SpanId |Request span id. -TraceFlags |W3C trace flag. -SeverityText |The severity text (also known as log level). -SeverityNumber |Numerical value of the severity. -Name |Short event identifier. -Body |The body of the log record. -Resource |Describes the source of the log. -Attributes |Additional information about the event. +| Field Name | Description | +| -------------- | -------------------------------------------- | +| Timestamp | Time when the event occurred. | +| TraceId | Request trace id. | +| SpanId | Request span id. | +| TraceFlags | W3C trace flag. | +| SeverityText | The severity text (also known as log level). | +| SeverityNumber | Numerical value of the severity. | +| Name | Short event identifier. | +| Body | The body of the log record. | +| Resource | Describes the source of the log. | +| Attributes | Additional information about the event. | Below is the detailed description of each field. @@ -238,14 +238,14 @@ less severe events (such as debug events), larger numerical values correspond to more severe events (such as errors and critical events). The following table defines the meaning of `SeverityNumber` value: -SeverityNumber range|Range name|Meaning ---------------------|----------|------- -1-4 |TRACE |A fine-grained debugging event. Typically disabled in default configurations. -5-8 |DEBUG |A debugging event. -9-12 |INFO |An informational event. Indicates that an event happened. -13-16 |WARN |A warning event. Not an error but is likely more important than an informational event. -17-20 |ERROR |An error event. Something went wrong. -21-24 |FATAL |A fatal error such as application or system crash. +| SeverityNumber range | Range name | Meaning | +| -------------------- | ---------- | -------------------------------------------------------------------------------------- | +| 1-4 | TRACE | A fine-grained debugging event. Typically disabled in default configurations. | +| 5-8 | DEBUG | A debugging event. | +| 9-12 | INFO | An informational event. Indicates that an event happened. | +| 13-16 | WARN | A warning event. Not an error but is likely more important than an informational event.| +| 17-20 | ERROR | An error event. Something went wrong. | +| 21-24 | FATAL | A fatal error such as application or system crash. | Smaller numerical values in each range represent less important (less severe) events. Larger numerical values in each range represent more important (more @@ -317,32 +317,32 @@ The following table defines the recommended short name for each `SeverityNumber` value. The short name can be used for example for representing the `SeverityNumber` in the UI: -SeverityNumber|Short Name ---------------|---------- -1 |TRACE -2 |TRACE2 -3 |TRACE3 -4 |TRACE4 -5 |DEBUG -6 |DEBUG2 -7 |DEBUG3 -8 |DEBUG4 -9 |INFO -10 |INFO2 -11 |INFO3 -12 |INFO4 -13 |WARN -14 |WARN2 -15 |WARN3 -16 |WARN4 -17 |ERROR -18 |ERROR2 -19 |ERROR3 -20 |ERROR4 -21 |FATAL -22 |FATAL2 -23 |FATAL3 -24 |FATAL4 +| SeverityNumber | Short Name | +| -------------- | ---------- | +| 1 | TRACE | +| 2 | TRACE2 | +| 3 | TRACE3 | +| 4 | TRACE4 | +| 5 | DEBUG | +| 6 | DEBUG2 | +| 7 | DEBUG3 | +| 8 | DEBUG4 | +| 9 | INFO | +| 10 | INFO2 | +| 11 | INFO3 | +| 12 | INFO4 | +| 13 | WARN | +| 14 | WARN2 | +| 15 | WARN3 | +| 16 | WARN4 | +| 17 | ERROR | +| 18 | ERROR2 | +| 19 | ERROR3 | +| 20 | ERROR4 | +| 21 | FATAL | +| 22 | FATAL2 | +| 23 | FATAL3 | +| 24 | FATAL4 | When an individual log record is displayed it is recommended to show both `SeverityText` and `SeverityNumber` values. A recommended combined string in @@ -995,19 +995,19 @@ Rest of SDIDs -> Attributes["syslog.*"] ### Google Cloud Logging -Field | Type | Description | Maps to Unified Model Field ------------------|--------------------| ------------------------------------------------------- | --------------------------- -timestamp | string | The time the event described by the log entry occurred. | Timestamp -resource | MonitoredResource | The monitored resource that produced this log entry. | Resource -log_name | string | The URL-encoded LOG_ID suffix of the log_name field identifies which log stream this entry belongs to. | Name -json_payload | google.protobuf.Struct | The log entry payload, represented as a structure that is expressed as a JSON object. | Body -proto_payload | google.protobuf.Any | The log entry payload, represented as a protocol buffer. | Body -text_payload | string | The log entry payload, represented as a Unicode string (UTF-8). | Body -severity | LogSeverity | The severity of the log entry. | Severity -trace | string | The trace associated with the log entry, if any. | TraceId -span_id | string | The span ID within the trace associated with the log entry. | SpanId -labels | map | A set of user-defined (key, value) data that provides additional information about the log entry. | Attributes -All other fields | | | Attributes["google.*"] +| Field | Type | Description | Maps to Unified Model Field | +| ----- | ---- | ----------- | --------------------------- | +| timestamp | string | The time the event described by the log entry occurred. | Timestamp | +| resource | MonitoredResource | The monitored resource that produced this log entry. | Resource | +| log_name | string | The URL-encoded LOG_ID suffix of the log_name field identifies which log stream this entry belongs to. | Name | +| json_payload | google.protobuf.Struct | The log entry payload, represented as a structure that is expressed as a JSON object. | Body | +| proto_payload | google.protobuf.Any | The log entry payload, represented as a protocol buffer. | Body | +| text_payload | string | The log entry payload, represented as a Unicode string (UTF-8). | Body | +| severity | LogSeverity | The severity of the log entry. | Severity | +| trace | string | The trace associated with the log entry, if any. | TraceId | +| span_id | string | The span ID within the trace associated with the log entry. | SpanId | +| labels | map | A set of user-defined (key, value) data that provides additional information about the log entry. | Attributes | +| All other fields | | | Attributes["google.*"] | ## Elastic Common Schema @@ -1332,19 +1332,19 @@ for an exhaustive list. ## Appendix B: `SeverityNumber` example mappings -|Syslog |WinEvtLog |Log4j |Zap |java.util.logging|SeverityNumber| -|-------------|-----------|------|------|-----------------|--------------| -| | |TRACE | | FINEST |TRACE | -|Debug |Verbose |DEBUG |Debug | FINER |DEBUG | -| | | | | FINE |DEBUG2 | -| | | | | CONFIG |DEBUG3 | -|Informational|Information|INFO |Info | INFO |INFO | -|Notice | | | | |INFO2 | -|Warning |Warning |WARN |Warn | WARNING |WARN | -|Error |Error |ERROR |Error | SEVERE |ERROR | -|Critical |Critical | |Dpanic| |ERROR2 | -|Emergency | | |Panic | |ERROR3 | -|Alert | |FATAL |Fatal | |FATAL | +| Syslog | WinEvtLog | Log4j | Zap | java.util.logging | SeverityNumber | +| ------ | --------- | ----- | --- | ----------------- | -------------- | +| | | TRACE | | FINEST | TRACE | +| Debug | Verbose | DEBUG | Debug | FINER | DEBUG | +| | | | | FINE | DEBUG2 | +| | | | | CONFIG | DEBUG3 | +| Informational | Information | INFO | Info | INFO | INFO | +| Notice | | | | | INFO2 | +| Warning | Warning | WARN | Warn | WARNING | WARN | +| Error | Error | ERROR | Error | SEVERE | ERROR | +| Critical | Critical | | Dpanic | | ERROR2 | +| Emergency | | | Panic | | ERROR3 | +| Alert | | FATAL | Fatal | | FATAL | ## References diff --git a/oteps/metrics/0003-measure-metric-type.md b/oteps/metrics/0003-measure-metric-type.md index 4f1d2a1ceb8..236a47f3d34 100644 --- a/oteps/metrics/0003-measure-metric-type.md +++ b/oteps/metrics/0003-measure-metric-type.md @@ -54,7 +54,7 @@ There are three kinds of metric instrument, `CumulativeMetric`, `GaugeMetric`, a Metric instruments are constructed through the `Meter` API. Constructing an instrument automatically registers it with the SDK. The common attributes of a metric instrument are: | Field | Description | -|------|-----------| +| ----- | ----------- | | Name | A string. | | Kind | One of Cumulative, Gauge, or Measure. | | Recommended Keys | Default aggregation keys. | @@ -119,13 +119,13 @@ Metric instruments are enabled by default, meaning that SDKs will export metric The kind-specific optional properties of a metric instrument are: | Property | Description | Metric kind | -|----------|-------------|-------------| -| Monotonic(true) | Indicates a cumulative that accepts only non-negative values | Cumulative (default) | -| | Indicate a gauge supports ascending value sequences starting at 0 | Gauge | +| -------- | ----------- | ----------- | +| Monotonic(true) | Indicates a cumulative that accepts only non-negative values | Cumulative (default) | +| | Indicate a gauge supports ascending value sequences starting at 0 | Gauge | | Monotonic(false) | Indicates a cumulative that accepts positive and negative values | Cumulative | -| | Indicate a gauge that expresses a monotonic cumulative value | Gauge (default) | -| Absolute(true) | Indicates a measure that accepts non-negative values | Measure (default) | -| Absolute(false) | Indicates a measure that accepts positive and negative values | Measure | +| | Indicate a gauge that expresses a monotonic cumulative value | Gauge (default) | +| Absolute(true) | Indicates a measure that accepts non-negative values | Measure (default) | +| Absolute(false) | Indicates a measure that accepts positive and negative values | Measure | ### RecordBatch API diff --git a/oteps/metrics/0088-metric-instrument-optional-refinements.md b/oteps/metrics/0088-metric-instrument-optional-refinements.md index cc623cc7f2b..c96f573a3c2 100644 --- a/oteps/metrics/0088-metric-instrument-optional-refinements.md +++ b/oteps/metrics/0088-metric-instrument-optional-refinements.md @@ -281,19 +281,19 @@ listed in the table below, of which only one has been standardized. Hypothetical future instrument names are _italicized_. | Foundation instrument | Sum-only? | Precomputed-sum? | Non-negative? | Non-negative-rate? | Instrument name _(hyptothetical)_ | -|--|--|--|--|--|--| -| Measure | sum-only | | non-negative | non-negative-rate | Counter | -| Measure | sum-only | precomputed-sum | | non-negative-rate | _CumulativeCounter_ | -| Measure | sum-only | | | | _UpDownCounter_ | -| Measure | sum-only | precomputed-sum | | | _UpDownCumulativeCounter_ | -| Measure | | | non-negative | | _AbsoluteDistribution_ | -| Measure | | | | | _Distribution_ | -| Observer | sum-only | | non-negative | non-negative-rate | _DeltaObserver_ | -| Observer | sum-only | precomputed-sum | | non-negative-rate | _CumulativeObserver_ | -| Observer | sum-only | | | | _UpDownDeltaObserver_ | -| Observer | sum-only | precomputed-sum | | | _UpDownCumulativeObserver_ | -| Observer | | | non-negative | | _AbsoluteLastValueObserver_ | -| Observer | | | | | _LastValueObserver_ | +| --- | ---- | ---- | ---- | --- | --- | +| Measure | sum-only | | non-negative | non-negative-rate | Counter | +| Measure | sum-only | precomputed-sum | | non-negative-rate | _CumulativeCounter_ | +| Measure | sum-only | | | | _UpDownCounter_ | +| Measure | sum-only | precomputed-sum | | | _UpDownCumulativeCounter_ | +| Measure | | | non-negative | | _AbsoluteDistribution_ | +| Measure | | | | | _Distribution_ | +| Observer | sum-only | | non-negative | non-negative-rate | _DeltaObserver_ | +| Observer | sum-only | precomputed-sum | | non-negative-rate | _CumulativeObserver_ | +| Observer | sum-only | | | | _UpDownDeltaObserver_ | +| Observer | sum-only | precomputed-sum | | | _UpDownCumulativeObserver_ | +| Observer | | | non-negative | | _AbsoluteLastValueObserver_ | +| Observer | | | | | _LastValueObserver_ | To arrive at this listing, several assumptions have been made. For example, the precomputed-sum and non-negative-rate refeinments are @@ -333,15 +333,15 @@ No API changes are called for in this proposal. The Prometheus system defines four kinds of [synchronous metric instrument](https://prometheus.io/docs/concepts/metric_types/). -| System | Metric Kind | Operation | Aggregation | Notes | -| ---------- | ------------ | ------------------- | -------------------- | ------------------- | -| Prometheus | Counter | Inc() | Sum | Sum of positive deltas | -| Prometheus | Counter | Add() | Sum | Sum of positive deltas | +| System | Metric Kind | Operation | Aggregation | Notes | +| ---------- | ------------ | ------------------- | -------------------- | ------------------------------------ | +| Prometheus | Counter | Inc() | Sum | Sum of positive deltas | +| Prometheus | Counter | Add() | Sum | Sum of positive deltas | | Prometheus | Gauge | Set() | Last Value | Non-additive or monotonic cumulative | -| Prometheus | Gauge | Inc()/Dec() | Sum | Sum of deltas | -| Prometheus | Gauge | Add()/Sub() | Sum | Sum of deltas | -| Prometheus | Histogram | Observe() | Histogram | Non-negative values | -| Prometheus | Summary | Observe() | Summary | Aggregation does not merge | +| Prometheus | Gauge | Inc()/Dec() | Sum | Sum of deltas | +| Prometheus | Gauge | Add()/Sub() | Sum | Sum of deltas | +| Prometheus | Histogram | Observe() | Histogram | Non-negative values | +| Prometheus | Summary | Observe() | Summary | Aggregation does not merge | Note that the Prometheus Gauge supports five methods (`Set`, `Inc`, `Dec`, `Add`, and `Sub`), one which sets the last value while the @@ -368,14 +368,14 @@ supported in Prometheus. The Statsd system supports only synchronous reporting. -| System | Metric Event | Operation | Aggregation | Notes | -| ------ | ------------ | ------------------- | -------------------- | ------------------- | -| Statsd | Count | Count() | Sum | Sum of deltas | -| Statsd | Gauge | Gauge() | Last Value | | -| Statsd | Histogram | Histogram() | Histogram | | -| Statsd | Distribution | Distribution() | _Not specified_ | A distribution summary | +| System | Metric Event | Operation | Aggregation | Notes | +| ------ | ------------ | ------------------- | -------------------- | ----------------------------------------------------- | +| Statsd | Count | Count() | Sum | Sum of deltas | +| Statsd | Gauge | Gauge() | Last Value | | +| Statsd | Histogram | Histogram() | Histogram | | +| Statsd | Distribution | Distribution() | _Not specified_ | A distribution summary | | Statsd | Timing | Timing() | _Not specified_ | Non-negative, distribution summary, Millisecond units | -| Statsd | Set | Set() | Cardinality | Unique value count | +| Statsd | Set | Set() | Cardinality | Unique value count | The Statsd Count operation translates into either a Counter, if increments are non-negative, or an _UpDownCounter_ if values may be @@ -399,12 +399,12 @@ element and no aggregation operator. The OpenCensus system defines three kinds of instrument: -| System | Metric Kind | Operation | Aggregation | Notes | -| ------ | ---------------- | -------------- | ----------------- | ------------------- | -| OpenCensus | Cumulative | Inc() | Sum | Positive deltas | -| OpenCensus | Gauge | Set() | LastValue | | -| OpenCensus | Gauge | Add() | Sum | Deltas | -| OpenCensus | Raw-Stats | Record() | Sum, Count, Mean, or Distribution | | +| System | Metric Kind | Operation | Aggregation | Notes | +| ---------- | ------------ | -------------- | --------------------------------- | ------------------- | +| OpenCensus | Cumulative | Inc() | Sum | Positive deltas | +| OpenCensus | Gauge | Set() | LastValue | | +| OpenCensus | Gauge | Add() | Sum | Deltas | +| OpenCensus | Raw-Stats | Record() | Sum, Count, Mean, or Distribution | | OpenCensus departed from convention with the introduction of a Views API, which makes it possible to support fewer kinds of instrument diff --git a/oteps/metrics/0098-metric-instruments-explained.md b/oteps/metrics/0098-metric-instruments-explained.md index f5b359b8044..b6429cd41e1 100644 --- a/oteps/metrics/0098-metric-instruments-explained.md +++ b/oteps/metrics/0098-metric-instruments-explained.md @@ -21,12 +21,12 @@ The following table summarizes the final proposed standard instruments resulting | Existing name | **Standard name** | Instrument kind | Function name | Input temporal quality | Default aggregation | Rate support (Monotonic) | Notes | | ------------- | ----------------------- | ----- | --------- | -------------- | ------------- | --- | ------------------------------------ | -| Counter | **Counter** | Sync | Add() | Delta | Sum | Yes | Per-request, part of a monotonic sum | -| | **UpDownCounter** | Sync | Add() | Delta | Sum | No | Per-request, part of a non-monotonic sum | -| Measure | **ValueRecorder** | Sync | Record() | Instantaneous | MinMaxSumCount | No | Per-request, any non-additive measurement | -| | **SumObserver** | Async | Observe() | Cumulative | Sum | Yes | Per-interval, reporting a monotonic sum | -| | **UpDownSumObserver** | Async | Observe() | Cumulative | Sum | No | Per-interval, reporting a non-monotonic sum | -| Observer | **ValueObserver** | Async | Observe() | Instantaneous | MinMaxSumCount | No | Per-interval, any non-additive measurement | +| Counter | **Counter** | Sync | Add() | Delta | Sum | Yes | Per-request, part of a monotonic sum | +| | **UpDownCounter** | Sync | Add() | Delta | Sum | No | Per-request, part of a non-monotonic sum | +| Measure | **ValueRecorder** | Sync | Record() | Instantaneous | MinMaxSumCount | No | Per-request, any non-additive measurement | +| | **SumObserver** | Async | Observe() | Cumulative | Sum | Yes | Per-interval, reporting a monotonic sum | +| | **UpDownSumObserver** | Async | Observe() | Cumulative | Sum | No | Per-interval, reporting a non-monotonic sum | +| Observer | **ValueObserver** | Async | Observe() | Instantaneous | MinMaxSumCount | No | Per-interval, any non-additive measurement | There are three synchronous instruments and three asynchronous instruments in this proposal, although a hypothetical 10 instruments were discussed in [OTEP 88][otep-88]. Although we consider them rational and logical, two categories of instrument are excluded in this proposal: synchronous cumulative instruments and asynchronous delta instruments. diff --git a/oteps/metrics/0146-metrics-prototype-scenarios.md b/oteps/metrics/0146-metrics-prototype-scenarios.md index 3a378f5180d..ca2634122f1 100644 --- a/oteps/metrics/0146-metrics-prototype-scenarios.md +++ b/oteps/metrics/0146-metrics-prototype-scenarios.md @@ -257,6 +257,7 @@ The application owner (developer Y) would only want the following metrics: | --------- | ---------- | --------- | ----------------- | ----------------- | ------------------- | | MachineA | 1234 | otel.org | 630 | 601 | 29 | | MachineA | 5678 | otel.org | 1005 | 1001 | 4 | + * Exception samples (exemplar) - in case HTTP 5xx happened, developer Y would want to see a sample request with trace id, span id and all the dimensions (IP, Port, etc.) diff --git a/oteps/trace/0168-sampling-propagation.md b/oteps/trace/0168-sampling-propagation.md index 5711280ca8e..723d10b8da9 100644 --- a/oteps/trace/0168-sampling-propagation.md +++ b/oteps/trace/0168-sampling-propagation.md @@ -77,16 +77,16 @@ shown in the following table. The p-value for known sampling probabilities is the negative base-2 logarithm of the probability: | p-value | Parent Probability | -| ----- | ----------- | -| 0 | 1 | -| 1 | 1/2 | -| 2 | 1/4 | -| ... | ... | -| N | 2**-N | -| ... | ... | -| 61 | 2**-61 | -| 62 | 2**-62 | -| 63 | 0 | +| ------- | ------------------ | +| 0 | 1 | +| 1 | 1/2 | +| 2 | 1/4 | +| ... | ... | +| N | 2**-N | +| ... | ... | +| 61 | 2**-61 | +| 62 | 2**-62 | +| 63 | 0 | [As specified in OTEP 170 for the Trace data model](0170-sampling-probability.md), @@ -348,8 +348,8 @@ respect to the incoming and outgoing values for `p`, `r`, and | Sampler | Incoming `r` | Incoming `p` | Incoming `sampled` | Outgoing `r` | Outgoing `p` | Outgoing `sampled` | | -- | -- | -- | -- | -- | -- | -- | | Parent | unused | expected | respected | checked and passed through | checked and passed through | checked and passed through | -| TraceIDRatio(Non-Root) | used | unused | ignored | checked and passed through | set to `s` | set to `p <= r` | -| TraceIDRatio(Root) | n/a | n/a | n/a | random variable | set to `s` | set to `p <= r` | +| TraceIDRatio(Non-Root) | used | unused | ignored | checked and passed through | set to `s` | set to `p <= r` | +| TraceIDRatio(Root) | n/a | n/a | n/a | random variable | set to `s` | set to `p <= r` | There are several cases where the resulting span's parent sampling probability is unknown: diff --git a/oteps/trace/0220-messaging-semantic-conventions-span-structure.md b/oteps/trace/0220-messaging-semantic-conventions-span-structure.md index 8c159117243..a05b18b911c 100644 --- a/oteps/trace/0220-messaging-semantic-conventions-span-structure.md +++ b/oteps/trace/0220-messaging-semantic-conventions-span-structure.md @@ -243,12 +243,12 @@ The following operations related to messages are covered by these semantic conventions: | Operation name | Description | -|----------------|-------------| -| `publish` | One or more messages are provided for publishing to an intermediary. | -| `create` | A message is created. | -| `receive` | One or more messages are requested by a consumer. | -| `deliver` | One or more messages are passed to a consumer. | -| `settle` | One or more messages are settled. | +| -------------- | ----------- | +| `publish` | One or more messages are provided for publishing to an intermediary. | +| `create` | A message is created. | +| `receive` | One or more messages are requested by a consumer. | +| `deliver` | One or more messages are passed to a consumer. | +| `settle` | One or more messages are settled. | For further details about each of those operations refer to the [section about trace structure](#trace-structure). @@ -257,13 +257,13 @@ For further details about each of those operations refer to the [section about t [Span kinds](../../specification/trace/api.md#spankind) SHOULD be set according to the following table, based on the operation a span describes. -| Operation name | Span kind| -|----------------|-------------| -| `publish` | `PRODUCER`, if no `create` spans are present. | -| `create` | `PRODUCER` | -| `receive` | `CONSUMER` | -| `deliver` | `CONSUMER` | -| `settle` | (see below) | +| Operation name | Span kind | +| -------------- | --------- | +| `publish` | `PRODUCER`, if no `create` spans are present. | +| `create` | `PRODUCER` | +| `receive` | `CONSUMER` | +| `deliver` | `CONSUMER` | +| `settle` | (see below) | The kind of `settle` spans should be set according to the [generic specification about span kinds](../../specification/trace/api.md#spankind), e. g. it should be set to `CLIENT` if the `settle` spans models a synchronous call diff --git a/oteps/trace/4673-experimental-probability-sampling.md b/oteps/trace/4673-experimental-probability-sampling.md index bda47aacdb6..5f573ad56ee 100644 --- a/oteps/trace/4673-experimental-probability-sampling.md +++ b/oteps/trace/4673-experimental-probability-sampling.md @@ -22,6 +22,9 @@ Changes to the document made below, summarized: [TRACESTATE_HANDLING]: https://github.com/open-telemetry/opentelemetry-specification/blob/ec3779c3d0044503a1ec [SDK_SPEC]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md +[SDK_SPEC#parentbased]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md#parentbased +[SDK_SPEC#sampler]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md#sampler +[SDK_SPEC#traceidratiobased]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md#traceidratiobased ## Overview diff --git a/specification/common/mapping-to-non-otlp.md b/specification/common/mapping-to-non-otlp.md index 73531654d7e..ae14e87b120 100644 --- a/specification/common/mapping-to-non-otlp.md +++ b/specification/common/mapping-to-non-otlp.md @@ -32,8 +32,8 @@ OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value pairs associated with the Span, Metric Data Point or LogRecord using the following mapping: -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| +| Attribute | Type | Description | Examples | Requirement Level | +| --- | --- | --- | --- | --- | | `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | Recommended | | `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | Recommended | @@ -42,8 +42,8 @@ The following deprecated aliases MUST also be reported with exact same values fo backward compatibility reasons: -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| +| Attribute | Type | Description | Examples | Requirement Level | +| --- | --- | --- | --- | --- | | `otel.library.name` | string | Deprecated, use the `otel.scope.name` attribute. | `io.opentelemetry.contrib.mongodb` | Recommended | | `otel.library.version` | string | Deprecated, use the `otel.scope.version` attribute. | `1.0.0` | Recommended | @@ -57,15 +57,15 @@ The following table defines the OpenTelemetry `Status`'s mapping to Span's key-value pairs: -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| +| Attribute | Type | Description | Examples | Requirement Level | +| --- | --- | --- | --- | --- | | `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK` | Recommended | | `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | Recommended | `otel.status_code` MUST be one of the following: -| Value | Description | -|---|---| +| Value | Description | +| --- | --- | | `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | | `ERROR` | The operation contains an error. | diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index aff527f5913..b6a789f5750 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -425,7 +425,6 @@ OTEL_{LANGUAGE}_{FEATURE} ``` [Boolean]: #boolean -[Float]: #float [Integer]: #integer [Duration]: #duration [Timeout]: #timeout diff --git a/specification/document-status.md b/specification/document-status.md index e5cf199a48a..1ba5c0d55fa 100644 --- a/specification/document-status.md +++ b/specification/document-status.md @@ -9,16 +9,16 @@ documents. The following table describes what the statuses mean. The support guarantees and allowed changes are governed by the maturity level of the document. Maturity levels are defined in [OTEP 0232](../oteps/0232-maturity-of-otel.md#explanation) and follow the OpenTelemetry project's standard framework for describing component maturity. -|Status |Explanation| -|--------------------|-----------| -|No explicit "Status"|Equivalent to Alpha.| -|Development |Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback around the UX of the component is desired, such as for configuration options, component observability, technical implementation details, and planned use-cases for the component. Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice.| -|Alpha |The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback. Bugs and performance problems are encouraged to be reported, but component owners might not work on them immediately. The component's interface and configuration options might often change without backward compatibility guarantees. Components at this stage might be dropped at any time without notice.| -|Beta |Same as Alpha, but the interfaces (API, configuration, generated telemetry) are treated as stable whenever possible. While there might be breaking changes between releases, component owners should try to minimize them. A component at this stage is expected to have had exposure to non-critical production workloads already during its Alpha phase, making it suitable for broader usage.| -|Release Candidate |The component is feature-complete and ready for broader usage. The component is ready to be declared stable, it might just need to be tested in more production environments before that can happen. Bugs and performance problems are expected to be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are only allowed under special circumstances. Whenever possible, users should be given prior notice of the breaking changes.| -|Stable |The component is ready for general availability. Bugs and performance problems should be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are only allowed under special circumstances. Whenever possible, users should be given prior notice of the breaking changes. See [stability guarantees](versioning-and-stability.md#stable) for details.| -|Deprecated |Development of this component is halted. No new versions are planned, and the component might be removed from its included distributions. Note that new issues will likely not be worked on except for critical security issues. Components that are included in distributions are expected to exist for at least two minor releases or six months, whichever happens later. They also MUST communicate in which version they will be removed.| -|Unmaintained |A component identified as unmaintained does not have an active code owner. Such components may have never been assigned a code owner, or a previously active code owner has not responded to requests for feedback within 6 weeks of being contacted. Issues and pull requests for unmaintained components SHOULD be labeled as such. After 6 months of being unmaintained, these components MAY be deprecated. Unmaintained components are actively seeking contributors to become code owners.| +| Status | Explanation | +| ------ | ----------- | +| No explicit "Status" | Equivalent to Alpha. | +| Development | Not all pieces of the component are in place yet, and it might not be available for users yet. Bugs and performance issues are expected to be reported. User feedback around the UX of the component is desired, such as for configuration options, component observability, technical implementation details, and planned use-cases for the component. Configuration options might break often depending on how things evolve. The component SHOULD NOT be used in production. The component MAY be removed without prior notice. | +| Alpha | The component is ready to be used for limited non-critical production workloads, and the authors of this component welcome user feedback. Bugs and performance problems are encouraged to be reported, but component owners might not work on them immediately. The component's interface and configuration options might often change without backward compatibility guarantees. Components at this stage might be dropped at any time without notice. | +| Beta | Same as Alpha, but the interfaces (API, configuration, generated telemetry) are treated as stable whenever possible. While there might be breaking changes between releases, component owners should try to minimize them. A component at this stage is expected to have had exposure to non-critical production workloads already during its Alpha phase, making it suitable for broader usage. | +| Release Candidate | The component is feature-complete and ready for broader usage. The component is ready to be declared stable, it might just need to be tested in more production environments before that can happen. Bugs and performance problems are expected to be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are only allowed under special circumstances. Whenever possible, users should be given prior notice of the breaking changes. | +| Stable | The component is ready for general availability. Bugs and performance problems should be reported, and there's an expectation that the component owners will work on them. Breaking changes, including configuration options and the component's output, are only allowed under special circumstances. Whenever possible, users should be given prior notice of the breaking changes. See [stability guarantees](versioning-and-stability.md#stable) for details. | +| Deprecated | Development of this component is halted. No new versions are planned, and the component might be removed from its included distributions. Note that new issues will likely not be worked on except for critical security issues. Components that are included in distributions are expected to exist for at least two minor releases or six months, whichever happens later. They also MUST communicate in which version they will be removed. | +| Unmaintained | A component identified as unmaintained does not have an active code owner. Such components may have never been assigned a code owner, or a previously active code owner has not responded to requests for feedback within 6 weeks of being contacted. Issues and pull requests for unmaintained components SHOULD be labeled as such. After 6 months of being unmaintained, these components MAY be deprecated. Unmaintained components are actively seeking contributors to become code owners. | The specification follows [OTEP 0232](../oteps/0232-maturity-of-otel.md#explanation) diff --git a/specification/entities/data-model.md b/specification/entities/data-model.md index 4c7c088657c..068b8edcc22 100644 --- a/specification/entities/data-model.md +++ b/specification/entities/data-model.md @@ -45,11 +45,11 @@ also runs on a host, so we say that the `process` entity is related to the The data model below defines a logical model for an entity (irrespective of the physical format and encoding of how entity data is recorded). -| Field | Type | Description | -|--------------|----------------------------------------|-----------------| -| Type | string | Defines the type of the entity. MUST not change during the lifetime of the entity. For example: "service" or "host". This field is required and MUST not be empty for valid entities. | -| Id | map | Attributes that identify the entity.

MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attributes. | -| Description | map | Descriptive (non-identifying) attributes of the entity.

MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) for attributes. | +| Field | Type | Description | +| ----- | ---- | ----------- | +| Type | string | Defines the type of the entity. MUST not change during the lifetime of the entity. For example: "service" or "host". This field is required and MUST not be empty for valid entities. | +| Id | map | Attributes that identify the entity.

MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attributes. | +| Description | map | Descriptive (non-identifying) attributes of the entity.

MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) for attributes. | ## Minimally Sufficient Identity diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md index ebd7c5abeca..adfcc3bdb7e 100644 --- a/specification/logs/data-model-appendix.md +++ b/specification/logs/data-model-appendix.md @@ -483,21 +483,21 @@ When mapping from the unified model to HEC, we apply this additional mapping: ### Google Cloud Logging -Field | Type | Description | Maps to Unified Model Field ------------------|--------------------| ------------------------------------------------------- | --------------------------- -timestamp | string | The time the event described by the log entry occurred. | Timestamp -resource | MonitoredResource | The monitored resource that produced this log entry. | Resource -log_name | string | The URL-encoded LOG_ID suffix of the log_name field identifies which log stream this entry belongs to. | Attributes["gcp.log_name"] -json_payload | google.protobuf.Struct | The log entry payload, represented as a structure that is expressed as a JSON object. | Body -proto_payload | google.protobuf.Any | The log entry payload, represented as a protocol buffer. | Body -text_payload | string | The log entry payload, represented as a Unicode string (UTF-8). | Body -severity | LogSeverity | The severity of the log entry. | Severity -trace | string | The trace associated with the log entry, if any. | TraceId -span_id | string | The span ID within the trace associated with the log entry. | SpanId -labels | map | A set of user-defined (key, value) data that provides additional information about the log entry. | Attributes -http_request | HttpRequest | The HTTP request associated with the log entry, if any. | Attributes["gcp.http_request"] -trace_sampled | boolean | The sampling decision of the trace associated with the log entry. | TraceFlags.SAMPLED -All other fields | | | Attributes["gcp.*"] +| Field | Type | Description | Maps to Unified Model Field | +| ----- | ---- | ----------- | --------------------------- | +| timestamp | string | The time the event described by the log entry occurred. | Timestamp | +| resource | MonitoredResource | The monitored resource that produced this log entry. | Resource | +| log_name | string | The URL-encoded LOG_ID suffix of the log_name field identifies which log stream this entry belongs to. | Attributes["gcp.log_name"] | +| json_payload | google.protobuf.Struct | The log entry payload, represented as a structure that is expressed as a JSON object. | Body | +| proto_payload | google.protobuf.Any | The log entry payload, represented as a protocol buffer. | Body | +| text_payload | string | The log entry payload, represented as a Unicode string (UTF-8). | Body | +| severity | LogSeverity | The severity of the log entry. | Severity | +| trace | string | The trace associated with the log entry, if any. | TraceId | +| span_id | string | The span ID within the trace associated with the log entry. | SpanId | +| labels | map | A set of user-defined (key, value) data that provides additional information about the log entry. | Attributes | +| http_request | HttpRequest | The HTTP request associated with the log entry, if any. | Attributes["gcp.http_request"] | +| trace_sampled | boolean | The sampling decision of the trace associated with the log entry. | TraceFlags.SAMPLED | +| All other fields | | | Attributes["gcp.*"] | ### Elastic Common Schema diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 6893df5c1cb..6ba173175ab 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -199,20 +199,20 @@ about the meaning of the field reviewing the examples may be helpful. Here is the list of fields in a log record: -Field Name |Description ----------------|-------------------------------------------- -Timestamp |Time when the event occurred. -ObservedTimestamp|Time when the event was observed. -TraceId |Request trace id. -SpanId |Request span id. -TraceFlags |W3C trace flag. -SeverityText |The severity text (also known as log level). -SeverityNumber |Numerical value of the severity. -Body |The body of the log record. -Resource |Describes the source of the log. -InstrumentationScope|Describes the scope that emitted the log. -Attributes |Additional information about the event. -EventName |Name that identifies the class / type of event. +| Field Name | Description | +| ---------- | ----------- | +| Timestamp | Time when the event occurred. | +| ObservedTimestamp | Time when the event was observed. | +| TraceId | Request trace id. | +| SpanId | Request span id. | +| TraceFlags | W3C trace flag. | +| SeverityText | The severity text (also known as log level). | +| SeverityNumber | Numerical value of the severity. | +| Body | The body of the log record. | +| Resource | Describes the source of the log. | +| InstrumentationScope | Describes the scope that emitted the log. | +| Attributes | Additional information about the event. | +| EventName | Name that identifies the class / type of event. | Below is the detailed description of each field. @@ -298,14 +298,14 @@ critical than an error with `SeverityNumber=20`. The following table defines the meaning of `SeverityNumber` value: -SeverityNumber range|Range name|Meaning ---------------------|----------|------- -1-4 |TRACE |A fine-grained debugging event. Typically disabled in default configurations. -5-8 |DEBUG |A debugging event. -9-12 |INFO |An informational event. Indicates that an event happened. -13-16 |WARN |A warning event. Not an error but is likely more important than an informational event. -17-20 |ERROR |An error event. Something went wrong. -21-24 |FATAL |A fatal error such as application or system crash. +| SeverityNumber range | Range name | Meaning | +| -------------------- | ---------- | --------------------------------------------------------------------------------------- | +| 1-4 | TRACE | A fine-grained debugging event. Typically disabled in default configurations. | +| 5-8 | DEBUG | A debugging event. | +| 9-12 | INFO | An informational event. Indicates that an event happened. | +| 13-16 | WARN | A warning event. Not an error but is likely more important than an informational event. | +| 17-20 | ERROR | An error event. Something went wrong. | +| 21-24 | FATAL | A fatal error such as application or system crash. | `SeverityNumber=0` MAY be used to represent an unspecified value. @@ -374,32 +374,32 @@ The following table defines the recommended short name for each `SeverityNumber` value. The short name can be used for example for representing the `SeverityNumber` in the UI: -SeverityNumber|Short Name ---------------|---------- -1 |TRACE -2 |TRACE2 -3 |TRACE3 -4 |TRACE4 -5 |DEBUG -6 |DEBUG2 -7 |DEBUG3 -8 |DEBUG4 -9 |INFO -10 |INFO2 -11 |INFO3 -12 |INFO4 -13 |WARN -14 |WARN2 -15 |WARN3 -16 |WARN4 -17 |ERROR -18 |ERROR2 -19 |ERROR3 -20 |ERROR4 -21 |FATAL -22 |FATAL2 -23 |FATAL3 -24 |FATAL4 +| SeverityNumber | Short Name | +| -------------- | ---------- | +| 1 | TRACE | +| 2 | TRACE2 | +| 3 | TRACE3 | +| 4 | TRACE4 | +| 5 | DEBUG | +| 6 | DEBUG2 | +| 7 | DEBUG3 | +| 8 | DEBUG4 | +| 9 | INFO | +| 10 | INFO2 | +| 11 | INFO3 | +| 12 | INFO4 | +| 13 | WARN | +| 14 | WARN2 | +| 15 | WARN3 | +| 16 | WARN4 | +| 17 | ERROR | +| 18 | ERROR2 | +| 19 | ERROR3 | +| 20 | ERROR4 | +| 21 | FATAL | +| 22 | FATAL2 | +| 23 | FATAL3 | +| 24 | FATAL4 | When an individual log record is displayed it is recommended to show both `SeverityText` and `SeverityNumber` values. A recommended combined string in diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 9c8736353ae..ef9315348e5 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -590,14 +590,14 @@ The Default Aggregation informs the SDK to use the Instrument `kind` to select an aggregation and `advisory` parameters to influence aggregation configuration parameters (as noted in the "Selected Aggregation" column). -| Instrument Kind | Selected Aggregation | -|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Counter](./api.md#counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | -| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | -| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) | -| [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) | -| [Gauge](./api.md#gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) | -| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) | +| Instrument Kind | Selected Aggregation | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [Counter](./api.md#counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | +| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | +| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) | +| [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) | +| [Gauge](./api.md#gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) | +| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) | | [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation), with the `ExplicitBucketBoundaries` [advisory parameter](./api.md#instrument-advisory-parameters) if provided | This Aggregation does not have any configuration parameters. diff --git a/specification/profiles/README.md b/specification/profiles/README.md index b0dfa1d3142..3405a8b2b96 100644 --- a/specification/profiles/README.md +++ b/specification/profiles/README.md @@ -59,5 +59,5 @@ To enhance the compatibility of OpenTelemetry Profiles with existing profiling tools, known values are utilized. | Profile field | Known values | -| -------------- | ------------ | - | original_payload_format | [pprof](https://github.com/google/pprof/tree/main/proto), [jfr](https://en.wikipedia.org/wiki/JDK_Flight_Recorder) or [linux_perf](https://perfwiki.github.io/) | +| ------------- | ------------ | +| original_payload_format | [pprof](https://github.com/google/pprof/tree/main/proto), [jfr](https://en.wikipedia.org/wiki/JDK_Flight_Recorder) or [linux_perf](https://perfwiki.github.io/) | diff --git a/specification/resource/data-model.md b/specification/resource/data-model.md index 6a9d579dc07..94bada584c4 100644 --- a/specification/resource/data-model.md +++ b/specification/resource/data-model.md @@ -32,9 +32,9 @@ or more attributes not associated with any entity. The data model below defines a logical model for an Resource (irrespective of the physical format and encoding of how resource data is recorded). -| Field | Type | Description | -|------------|----------|-----------------| -| Entities | set\ | Defines the set of Entities associated with this resource.

[Entity is defined here](../entities/data-model.md) | +| Field | Type | Description | +| ----- | ---- | ----------- | +| Entities | set\ | Defines the set of Entities associated with this resource.

[Entity is defined here](../entities/data-model.md) | | Attributes | map\ | Additional Attributes that identify the resource.

MUST not change during the lifetime of the resource.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). | ## Identity diff --git a/specification/trace/api.md b/specification/trace/api.md index 2efaa18459e..01afd30e602 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -335,11 +335,11 @@ Generality SHOULD be prioritized over human-readability. For example, here are potential span names for an endpoint that gets a hypothetical account information: -| Span Name | Guidance | -| ----------------- | ------------ | -| `get` | Too general | -| `get_account/42` | Too specific | -| `get_account` | Good, and account_id=42 would make a nice Span attribute | +| Span Name | Guidance | +| --------- | -------- | +| `get` | Too general | +| `get_account/42` | Too specific | +| `get_account` | Good, and account_id=42 would make a nice Span attribute | | `get_account/{accountId}` | Also good (using the "HTTP route") | The `Span`'s start and end timestamps reflect the elapsed real time of the diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 4542b9cfcee..e59f154e27c 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -579,13 +579,13 @@ Optional parameters: * `localParentSampled(Sampler)` (default: AlwaysOn) * `localParentNotSampled(Sampler)` (default: AlwaysOff) -|Parent| parent.isRemote() | parent.IsSampled()| Invoke sampler| -|--|--|--|--| -|absent| n/a | n/a |`root()`| -|present|true|true|`remoteParentSampled()`| -|present|true|false|`remoteParentNotSampled()`| -|present|false|true|`localParentSampled()`| -|present|false|false|`localParentNotSampled()`| +| Parent | parent.isRemote() | parent.IsSampled() | Invoke sampler | +| --- | --- | --- | --- | +| absent | n/a | n/a | `root()` | +| present | true | true | `remoteParentSampled()` | +| present | true | false | `remoteParentNotSampled()` | +| present | false | true | `localParentSampled()` | +| present | false | false | `localParentNotSampled()` | #### JaegerRemoteSampler @@ -735,7 +735,7 @@ This example creates a configuration where: **Status**: [Development](../document-status.md) -The [W3C Trace Context Level 2][W3CCONTEXTMAIN] Candidate Recommendation includes [a Random trace flag][W3CCONTEXTRANDOMFLAG] for indicating that the TraceID contains 56 random bits, specified for statistical purposes. +The [W3C Trace Context Level 2][W3CCONTEXTLEVEL2] Candidate Recommendation includes [a Random trace flag][W3CCONTEXTRANDOMFLAG] for indicating that the TraceID contains 56 random bits, specified for statistical purposes. This flag indicates that [the least-significant ("rightmost") 7 bytes or 56 bits of the TraceID are random][W3CCONTEXTTRACEID]. Note the Random flag does not propagate through [Trace Context Level 1][W3CCONTEXTLEVEL1] implementations, which do not recognize the flag. @@ -746,7 +746,7 @@ OpenTelemetry defines an optional [explicit randomness value][OTELRVALUE] encode This specification recommends the use of either TraceID randomness or explicit randomness, which ensures that samplers always have sufficient randomness when using W3C Trace Context propagation. -[W3CCONTEXTMAIN]: https://www.w3.org/TR/trace-context-2/ +[W3CCONTEXTLEVEL2]: https://www.w3.org/TR/trace-context-2/ [W3CCONTEXTLEVEL1]: https://www.w3.org/TR/trace-context/ [W3CCONTEXTTRACEID]: https://www.w3.org/TR/trace-context-2/#randomness-of-trace-id [W3CCONTEXTTRACESTATE]: https://www.w3.org/TR/trace-context-2/#tracestate-header diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index 32b39d5da0b..dcb990c77c4 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -32,23 +32,23 @@ Zipkin's v2 API is defined in the The following table summarizes the major transformations between OpenTelemetry and Zipkin. -| OpenTelemetry | Zipkin | Notes | -| -------------------------- | ---------------- | --------------------------------------------------------------------------------------------- | -| Span.TraceId | Span.trace_id | | -| Span.ParentId | Span.parent_id | | -| Span.SpanId | Span.id | | -| Span.TraceState | TBD | TBD | -| Span.Name | Span.name | | -| Span.Kind | Span.kind | See [SpanKind](#spankind) for values mapping | -| Span.StartTime | Span.timestamp | See [Unit of time](#unit-of-time) | -| Span.EndTime | Span.duration | Duration is calculated based on StartTime and EndTime. See also [Unit of time](#unit-of-time) | -| Span.Attributes | Add to Span.tags | See [Attributes](../../common/README.md#attribute) for data types for the mapping. | +| OpenTelemetry | Zipkin | Notes | +| -------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- | +| Span.TraceId | Span.trace_id | | +| Span.ParentId | Span.parent_id | | +| Span.SpanId | Span.id | | +| Span.TraceState | TBD | TBD | +| Span.Name | Span.name | | +| Span.Kind | Span.kind | See [SpanKind](#spankind) for values mapping | +| Span.StartTime | Span.timestamp | See [Unit of time](#unit-of-time) | +| Span.EndTime | Span.duration | Duration is calculated based on StartTime and EndTime. See also [Unit of time](#unit-of-time) | +| Span.Attributes | Add to Span.tags | See [Attributes](../../common/README.md#attribute) for data types for the mapping. | | Span.DroppedAttributesCount| Add to Span.tags | See [Dropped Attributes Count](../../common/mapping-to-non-otlp.md#dropped-attributes-count) for tag name to use. | -| Span.Events | Span.annotations | See [Events](#events) for the mapping format. | +| Span.Events | Span.annotations | See [Events](#events) for the mapping format. | | Span.DroppedEventsCount | Add to Span.tags | See [Dropped Events Count](../../common/mapping-to-non-otlp.md#dropped-events-count) for tag name to use. | -| Span.Links | TBD | TBD | +| Span.Links | TBD | TBD | | Span.DroppedLinksCount | Add to Span.tags | See [Dropped Links Count](../../common/mapping-to-non-otlp.md#dropped-links-count) for tag name to use. | -| Span.Status | Add to Span.tags | See [Status](#status) for tag names to use. | +| Span.Status | Add to Span.tags | See [Status](#status) for tag names to use. | TBD : This is work in progress document and it is currently doesn't specify mapping for these fields: @@ -92,11 +92,11 @@ Zipkin. | OpenTelemetry | Zipkin | Note | | ------------- | ------ | ---- | -| `SpanKind.CLIENT`|`SpanKind.CLIENT`|| -| `SpanKind.SERVER`|`SpanKind.SERVER`|| -| `SpanKind.CONSUMER`|`SpanKind.CONSUMER`|| -| `SpanKind.PRODUCER`|`SpanKind.PRODUCER` || -| `SpanKind.INTERNAL`|`null` |must be omitted (set to `null`)| +| `SpanKind.CLIENT` | `SpanKind.CLIENT` | | +| `SpanKind.SERVER` | `SpanKind.SERVER` | | +| `SpanKind.CONSUMER` | `SpanKind.CONSUMER` | | +| `SpanKind.PRODUCER` | `SpanKind.PRODUCER` | | +| `SpanKind.INTERNAL` | `null` | must be omitted (set to `null`) | ### Remote endpoint @@ -159,10 +159,10 @@ In the latter case it MUST NOT be reported. The following table defines the OpenTelemetry `Status` to Zipkin `tags` mapping. -| Status|Tag Key| Tag Value | -|--|--|--| -|Code | `otel.status_code` | Name of the code, either `OK` or `ERROR`. MUST NOT be set if the code is `UNSET`. | -|Description| `error` | Description of the `Status`. MUST be set if the code is `ERROR`, use an empty string if Description has no value. MUST NOT be set for `OK` and `UNSET` codes. | +| Status | Tag Key | Tag Value | +| --- | --- | ---- | +| Code | `otel.status_code` | Name of the code, either `OK` or `ERROR`. MUST NOT be set if the code is `UNSET`. | +| Description | `error` | Description of the `Status`. MUST be set if the code is `ERROR`, use an empty string if Description has no value. MUST NOT be set for `OK` and `UNSET` codes. | Note: The `error` tag should only be set if `Status` is `Error`. If a boolean version (`{"error":false}` or `{"error":"false"}`) is present, it SHOULD be diff --git a/specification/trace/tracestate-probability-sampling.md b/specification/trace/tracestate-probability-sampling.md index 67e642f96c6..0c433aaac42 100644 --- a/specification/trace/tracestate-probability-sampling.md +++ b/specification/trace/tracestate-probability-sampling.md @@ -437,7 +437,7 @@ The following table shows values computed by the method above for 1-in-N probabi | 1-in-N | Input probability | Threshold (precision 3, 4, 5) | Actual probability (precision 3, 4, 5) | Exact Adjusted Count (precision 3, 4, 5) | -|---------|--------------------|------------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------| +| ------- | ------------------ | ---------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- | | 1 | 1 | 0
0
0 | 1
1
1 | 1
1
1 | | 2 | 0.5 | 8
8
8 | 0.5
0.5
0.5 | 2
2
2 | | 3 | 0.3333333333333333 | aab
aaab
aaaab | 0.333251953125
0.3333282470703125
0.33333301544189453 | 3.0007326007326007
3.00004577706569
3.0000028610256777 | @@ -449,8 +449,8 @@ The following table shows values computed by the method above for 1-in-N probabi | 100 | 0.01 | fd71
fd70a
fd70a4 | 0.0099945068359375
0.010000228881835938
0.009999990463256836 | 100.05496183206107
99.99771123402633
100.00009536752259 | | 1000 | 0.001 | ffbe7
ffbe77
ffbe76d | 0.0010004043579101562
0.0009999871253967285
0.000999998301267624 | 999.5958055290753
1000.012874769029
1000.0016987352618 | | 10000 | 0.0001 | fff972
fff9724
fff97247 | 0.00010001659393310547
0.00010000169277191162
0.00010000006295740604 | 9998.340882002383
9999.830725674266
9999.99370426336 | -| 100000 | 0.00001 | ffff584
ffff583a
ffff583a5 | 9.998679161071777e-06
1.00000761449337e-05
1.0000003385357559e-05 | 100013.21013412817
99999.238556461
99999.96614643588 | -| 1000000 | 0.000001 | ffffef4
ffffef39
ffffef391 | 9.98377799987793e-07
1.00000761449337e-06
9.999930625781417e-07 | 1.0016248358208955e+06
999992.38556461
1.0000069374699865e+06 | +| 100000 | 0.00001 | ffff584
ffff583a
ffff583a5 | 9.998679161071777e-06
1.00000761449337e-05
1.0000003385357559e-05 | 100013.21013412817
99999.238556461
99999.96614643588 | +| 1000000 | 0.000001 | ffffef4
ffffef39
ffffef391 | 9.98377799987793e-07
1.00000761449337e-06
9.999930625781417e-07 | 1.0016248358208955e+06
999992.38556461
1.0000069374699865e+06 | ### Converting integer threshold to a `T`-value From 2b8713610235703baf3ff87cc37be31a6378e8a2 Mon Sep 17 00:00:00 2001 From: James Thompson Date: Tue, 2 Dec 2025 11:30:25 +1100 Subject: [PATCH 2/2] Tweaked links --- oteps/trace/4673-experimental-probability-sampling.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/oteps/trace/4673-experimental-probability-sampling.md b/oteps/trace/4673-experimental-probability-sampling.md index 5f573ad56ee..f4b33f1d2e8 100644 --- a/oteps/trace/4673-experimental-probability-sampling.md +++ b/oteps/trace/4673-experimental-probability-sampling.md @@ -20,11 +20,11 @@ Changes to the document made below, summarized: added the new specification. - Remove the table of contents. -[TRACESTATE_HANDLING]: https://github.com/open-telemetry/opentelemetry-specification/blob/ec3779c3d0044503a1ec -[SDK_SPEC]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md -[SDK_SPEC#parentbased]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md#parentbased -[SDK_SPEC#sampler]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md#sampler -[SDK_SPEC#traceidratiobased]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/tracestate-handling.md#traceidratiobased +[TRACESTATE_HANDLING]: https://github.com/open-telemetry/opentelemetry-specification/blob/ec3779c3d0044503a1ec/specification/trace/tracestate-handling.md +[SDK_SPEC]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/sdk.md +[SDK_SPEC#parentbased]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/sdk.md#parentbased +[SDK_SPEC#sampler]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/sdk.md#sampling +[SDK_SPEC#traceidratiobased]: https://github.com/open-telemetry/opentelemetry-specification/blob/03e4ea2748e18e63d1e00e58e373ca55768fb1b0/specification/trace/sdk.md#traceidratiobased ## Overview