From 450765613674517916996702363be81869a85cad Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Thu, 22 Oct 2020 15:14:39 +0200 Subject: [PATCH 01/26] Add an option to limit span attribute length Docs are based on existing Java implenetation https://github.com/open-telemetry/opentelemetry-java/pull/1484 --- spec-compliance-matrix.md | 2 ++ specification/sdk-environment-variables.md | 15 ++++++++++----- specification/trace/sdk.md | 12 +++++++++++- 3 files changed, 23 insertions(+), 6 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 35b7d5cea8a..9f134700646 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -48,6 +48,7 @@ status of the feature is not known. |links collection size limit | | | + | | | | | | | | |[Span attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#set-attributes)| |SetAttribute | + | + | + | + | + | + | + | + | + | + | +|Span attribute size limit | | + | | | | | | | | | |Set order preserved | + | - | + | + | + | + | + | + | + | + | |String type | + | + | + | + | + | + | + | + | + | + | |Boolean type | + | + | + | + | + | + | + | + | + | + | @@ -128,6 +129,7 @@ status of the feature is not known. |OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | | | | | | | | | | | |OTEL_SPAN_EVENT_COUNT_LIMIT | | | | | | | | | | | |OTEL_SPAN_LINK_COUNT_LIMIT | | | | | | | | | | | +|OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | | | | | | | | | | | ## Exporters diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 7245634b4fb..afdea3c2f08 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -23,12 +23,17 @@ Additional values can be specified in the respective SDK's documentation, in cas | OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE | ## Span Collection Limits +Moved [here](#span-limits). This section serves as +a permalink. -| Name | Description | Default | Notes | -| ------------------------------- | ------------------------------------ | ------- | ----- | -| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 1000 | | -| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 1000 | | -| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 1000 | | +## Span Limits + +| Name | Description | Default | Notes | +| ------------------------------- | ------------------------------------- | ------- | ----- | +| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 1000 | | +| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 1000 | | +| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 1000 | | +| OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | Maximum allowed span attribute length | -1 | -1 is treated as infinity, any other negative value is invalid. Non-integer values are invalid. | ## OTLP Exporter diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index aee09e6c4eb..067982fcda5 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -8,6 +8,7 @@ * [Tracer Provider](#tracer-provider) * [Additional Span Interfaces](#additional-span-interfaces) * [Limits on Span Collections](#limits-on-span-collections) +* [Limits on Span Collections and Attributes](#limits-on-span-collections-and-attributes) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter) @@ -265,6 +266,10 @@ Thus, the SDK specification defines sets of possible requirements for or a getter could be provided). ## Limits on Span Collections +Moved [here](#limits-on-span-collections-and-attributes). This section serves as +a permalink. + +## Limits on Span Collections and Attributes Erroneous code can add unintended attributes, events, and links to a span. If these collections are unbounded, they can quickly exhaust available memory, @@ -274,8 +279,13 @@ To protect against such errors, SDK Spans MAY discard attributes, links, and events that would increase the number of elements of each collection beyond the recommended limit of 1000 elements. SDKs MAY provide a way to change this limit. +Similarly SDK Spans can be configured to truncate attribute values. By default, +no attribute values are truncated, however, a limit, if set, will be applied to +truncate attribute value expressed as a string of characters, so that its length +does not exceed the limit. + If there is a configurable limit, the SDK SHOULD honor the environment variables -specified in [SDK environment variables](../sdk-environment-variables.md#span-collection-limits). +specified in [SDK environment variables](../sdk-environment-variables.md#span-limits). There SHOULD be a log emitted to indicate to the user that an attribute, event, or link was discarded due to such a limit. To prevent excessive logging, the log From deca25bf77e8996b87f07eaf9b08e3850b5d8c6b Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Thu, 22 Oct 2020 21:21:55 +0200 Subject: [PATCH 02/26] Change default value of OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT to empty --- specification/sdk-environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index afdea3c2f08..a64862372c5 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -33,7 +33,7 @@ a permalink. | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 1000 | | | OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 1000 | | | OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 1000 | | -| OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | Maximum allowed span attribute length | -1 | -1 is treated as infinity, any other negative value is invalid. Non-integer values are invalid. | +| OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | Maximum allowed span attribute length | | Empty value is treated as infinity. Non-integer and negative values are invalid. | ## OTLP Exporter From 748eae0f1003eed28940915202b1c9eaf11f86ba Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Thu, 22 Oct 2020 21:30:40 +0200 Subject: [PATCH 03/26] Fix wording in Span attribute limiting section --- specification/trace/sdk.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 067982fcda5..395e7e7ec27 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -279,10 +279,11 @@ To protect against such errors, SDK Spans MAY discard attributes, links, and events that would increase the number of elements of each collection beyond the recommended limit of 1000 elements. SDKs MAY provide a way to change this limit. -Similarly SDK Spans can be configured to truncate attribute values. By default, -no attribute values are truncated, however, a limit, if set, will be applied to -truncate attribute value expressed as a string of characters, so that its length -does not exceed the limit. +Similarly, SDKs MAY be configured to truncate attribute values. By default, attribute +values SHOULD NOT be truncated. If an SDK provides a way to set this limit and the +limit is set, then for each span attribute value, serialized into a string, +if it exceeds that limit, SDK Spans SHOULD truncate that value, so that its length +is at most equal to the limit. If there is a configurable limit, the SDK SHOULD honor the environment variables specified in [SDK environment variables](../sdk-environment-variables.md#span-limits). From e7e54b3e46d2b043f87e92107eb85c99bd57881a Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Fri, 23 Oct 2020 13:45:05 +0200 Subject: [PATCH 04/26] Introduce metric label value size limit --- specification/metrics/sdk.md | 19 +++++++++++++++++++ specification/sdk-environment-variables.md | 6 ++++++ specification/trace/sdk.md | 2 +- 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 91a37d1db17..89d5e02ae9e 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -494,3 +494,22 @@ and Sketch. TODO: T.B.D.: DDSketch considered a good choice for ValueRecorder instrument default aggregation. + +## Limits on Metrics + +Erroneous code can add unintended labels to a span. If they are unbounded, they +can quickly exhaust available memory, resulting in crashes that are difficult to +recover from safely. + +To protect against such errors, SDKs MAY be configured to truncate label values. +By default, label values SHOULD NOT be truncated. If an SDK provides a way to set +this limit and the limit is set, then for each Metric label value, if its length +exceeds that limit, SDK Spans SHOULD truncate that value, so that its length is +at most equal to the limit. + +If there is a configurable limit, the SDK SHOULD honor the environment variables +specified in [SDK environment variables](../sdk-environment-variables.md#metric-limits). + +There SHOULD be a log emitted to indicate to the user that any value was discarded +or truncated due to such a limit. To prevent excessive logging, the log should +not be emitted more than once per metric or value. diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index a64862372c5..d3abce2126c 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -35,6 +35,12 @@ a permalink. | OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 1000 | | | OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | Maximum allowed span attribute length | | Empty value is treated as infinity. Non-integer and negative values are invalid. | +## Metric Limits + +| Name | Description | Default | Notes | +| ---------------------------- | ----------------------------------- | ------- | ----- | +| OTEL_METRIC_LABEL_SIZE_LIMIT | Maximum allowed metric value length | | Empty value is treated as infinity. Non-integer and negative values are invalid. | + ## OTLP Exporter See [OpenTelemetry Protocol Exporter Configuration Options](./protocol/exporter.md). diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 395e7e7ec27..18d0b097193 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -290,7 +290,7 @@ specified in [SDK environment variables](../sdk-environment-variables.md#span-li There SHOULD be a log emitted to indicate to the user that an attribute, event, or link was discarded due to such a limit. To prevent excessive logging, the log -should not be emitted once per span, or per discarded attribute, event, or links. +should not be emitted more than once per span, attribute, event, or link. ## Span processor From 10af7baa9718158a2d99743102866abce52668a1 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Fri, 23 Oct 2020 13:49:10 +0200 Subject: [PATCH 05/26] Spec compliance for truncating metric label values --- spec-compliance-matrix.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 9f134700646..53748d0d53f 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -82,7 +82,7 @@ status of the feature is not known. |Feature |Go|Java|JS |Python|Ruby|Erlang|PHP|Rust|C++|.Net| |----------------------------------------------|--|----|---|------|----|------|---|----|---|----| -|TBD| +|Metric label value size limit | | | | | | | | | | | ## Resource @@ -130,6 +130,7 @@ status of the feature is not known. |OTEL_SPAN_EVENT_COUNT_LIMIT | | | | | | | | | | | |OTEL_SPAN_LINK_COUNT_LIMIT | | | | | | | | | | | |OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | | | | | | | | | | | +|OTEL_METRIC_LABEL_SIZE_LIMIT | | | | | | | | | | | ## Exporters From ed9bc5f0833f0b9828a656c5839e79834a352e2e Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Fri, 23 Oct 2020 17:00:32 +0200 Subject: [PATCH 06/26] Limits docs improvements Co-authored-by: Armin Ruech --- specification/metrics/sdk.md | 4 ++-- specification/sdk-environment-variables.md | 4 +--- specification/trace/sdk.md | 7 ++----- 3 files changed, 5 insertions(+), 10 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 89d5e02ae9e..7acd7967cb2 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -497,14 +497,14 @@ instrument default aggregation. ## Limits on Metrics -Erroneous code can add unintended labels to a span. If they are unbounded, they +Erroneous code can add unintended labels to a metric. If they are unbounded, they can quickly exhaust available memory, resulting in crashes that are difficult to recover from safely. To protect against such errors, SDKs MAY be configured to truncate label values. By default, label values SHOULD NOT be truncated. If an SDK provides a way to set this limit and the limit is set, then for each Metric label value, if its length -exceeds that limit, SDK Spans SHOULD truncate that value, so that its length is +exceeds that limit, SDKs SHOULD truncate that value, so that its length is at most equal to the limit. If there is a configurable limit, the SDK SHOULD honor the environment variables diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index d3abce2126c..6aca07b067d 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -22,9 +22,7 @@ Additional values can be specified in the respective SDK's documentation, in cas | OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | | | OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE | -## Span Collection Limits -Moved [here](#span-limits). This section serves as -a permalink. + ## Span Limits diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 18d0b097193..f85508db5bc 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -7,7 +7,6 @@ * [Sampling](#sampling) * [Tracer Provider](#tracer-provider) * [Additional Span Interfaces](#additional-span-interfaces) -* [Limits on Span Collections](#limits-on-span-collections) * [Limits on Span Collections and Attributes](#limits-on-span-collections-and-attributes) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter) @@ -265,9 +264,7 @@ Thus, the SDK specification defines sets of possible requirements for (for example, the `Span` could be one of the parameters passed to such a function, or a getter could be provided). -## Limits on Span Collections -Moved [here](#limits-on-span-collections-and-attributes). This section serves as -a permalink. + ## Limits on Span Collections and Attributes @@ -282,7 +279,7 @@ the recommended limit of 1000 elements. SDKs MAY provide a way to change this li Similarly, SDKs MAY be configured to truncate attribute values. By default, attribute values SHOULD NOT be truncated. If an SDK provides a way to set this limit and the limit is set, then for each span attribute value, serialized into a string, -if it exceeds that limit, SDK Spans SHOULD truncate that value, so that its length +if it exceeds that limit, SDKs SHOULD truncate that value, so that its length is at most equal to the limit. If there is a configurable limit, the SDK SHOULD honor the environment variables From dabb2929e1d10eba9c8e6d2f2adaaa1d4d758e4d Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Mon, 26 Oct 2020 14:23:09 +0100 Subject: [PATCH 07/26] Fix traces limiting requirement Co-authored-by: Nikita Salnikov-Tarnovski --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index f85508db5bc..7425cf396cb 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -279,7 +279,7 @@ the recommended limit of 1000 elements. SDKs MAY provide a way to change this li Similarly, SDKs MAY be configured to truncate attribute values. By default, attribute values SHOULD NOT be truncated. If an SDK provides a way to set this limit and the limit is set, then for each span attribute value, serialized into a string, -if it exceeds that limit, SDKs SHOULD truncate that value, so that its length +if it exceeds that limit, SDKs MUST truncate that value, so that its length is at most equal to the limit. If there is a configurable limit, the SDK SHOULD honor the environment variables From 4102464b3e3858d5c817139384462bcadf8b313f Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 27 Oct 2020 19:18:32 +0100 Subject: [PATCH 08/26] Expand span attribute limits to all attributes --- specification/common/common.md | 36 ++++++++++++++++++++++ specification/metrics/sdk.md | 16 ++-------- specification/sdk-environment-variables.md | 11 +++++-- specification/trace/sdk.md | 16 +++------- 4 files changed, 51 insertions(+), 28 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 974cf518214..83bc21c4c8a 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -6,6 +6,7 @@ Table of Contents - [Attributes](#attributes) + - [Attribute Limits](#attribute-limits) - [Attribute and Label Naming](#attribute-and-label-naming) @@ -38,6 +39,41 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). +### Attribute Limits + +Execution of erroneous code can result in unintended attributes. If there is no +limits placed on attributes, they can quickly exhaust available memory, resulting +in crashes that are difficult to recover from safely. + +SDKs MAY be configured to truncate attribute values. By default, attribute values +SHOULD NOT be truncated. If an SDK provides a way to set an attribute value size +limit and the limit is set, then for each attribute value, serialized into a string, +if it exceeds that limit, SDK Spans SHOULD truncate that value, so that its length +is at most equal to the limit. However if a serialized value does not exceed the +size limit, then it shouldn't be serialized. + +SDKs SHOULD choose any serialization protocol, which is performant and appropriate +for the language and/or environment they are implemented in. Please note that the +aforementioned behavior MAY yield a previously unexpected type. For example, if +an attribute was set and its value was an array, then after serialization, due to +an exceeded size limit, its value SHOULD be a string. + +There SHOULD be a log emitted to indicate to the user that an attribute was truncated. +To prevent excessive logging, the log MUST NOT be emitted more than once per item +on which an attribute is set. + +To define a limit SDKs SHOULD honor the environment variables specified in +[SDK environment variables](../sdk-environment-variables.md#attribute-limits). If an +SDK does not implement truncation mechanism for all implementations of attributes, +then it SHOULD NOT offer a single global environment variable for such a limit. +SDKs SHOULD only offer environment variables for these types of attributes, for +which that SDK implements truncation mechanism. + +Due to a possible increased implementation complexity, attribute value size limit +MUST NOT be set to any number lower than 32. Please note that certain very low limits +could even result in truncation of small numbers or booleans, and such a behavior +is not valuable for preventing SDKs from exhausting large amounts of memory. + ## Attribute and Label Naming _This section applies to Resource, Span and Log attribute names (also known as diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7acd7967cb2..3d7339b3c3c 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -497,19 +497,9 @@ instrument default aggregation. ## Limits on Metrics -Erroneous code can add unintended labels to a metric. If they are unbounded, they -can quickly exhaust available memory, resulting in crashes that are difficult to -recover from safely. - -To protect against such errors, SDKs MAY be configured to truncate label values. -By default, label values SHOULD NOT be truncated. If an SDK provides a way to set -this limit and the limit is set, then for each Metric label value, if its length -exceeds that limit, SDKs SHOULD truncate that value, so that its length is -at most equal to the limit. +SDKs MAY be configured to truncate metric label values. This behaviour is the same +as the truncation behavior of attribute values documented in +[attributes limit section](../common/common.md#attribute-limits). If there is a configurable limit, the SDK SHOULD honor the environment variables specified in [SDK environment variables](../sdk-environment-variables.md#metric-limits). - -There SHOULD be a log emitted to indicate to the user that any value was discarded -or truncated due to such a limit. To prevent excessive logging, the log should -not be emitted more than once per metric or value. diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 6aca07b067d..d20edba0fd0 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -22,8 +22,13 @@ Additional values can be specified in the respective SDK's documentation, in cas | OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | | | OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE | - +## Attribute Limits +| Name | Description | Default | Notes | +| ------------------------------- | ------------------------------------ | ------- | ----- | +| OTEL_ATTRIBUTE_VALUE_SIZE_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. MUST not be lower than 32. | + + ## Span Limits | Name | Description | Default | Notes | @@ -31,13 +36,13 @@ Additional values can be specified in the respective SDK's documentation, in cas | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 1000 | | | OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 1000 | | | OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 1000 | | -| OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | Maximum allowed span attribute length | | Empty value is treated as infinity. Non-integer and negative values are invalid. | +| OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | Maximum allowed span attribute length | | See notes for OTEL_ATTRIBUTE_VALUE_SIZE_LIMIT | ## Metric Limits | Name | Description | Default | Notes | | ---------------------------- | ----------------------------------- | ------- | ----- | -| OTEL_METRIC_LABEL_SIZE_LIMIT | Maximum allowed metric value length | | Empty value is treated as infinity. Non-integer and negative values are invalid. | +| OTEL_METRIC_LABEL_SIZE_LIMIT | Maximum allowed metric value length | | See notes for OTEL_ATTRIBUTE_VALUE_SIZE_LIMIT | ## OTLP Exporter diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 7425cf396cb..aee09e6c4eb 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -7,7 +7,7 @@ * [Sampling](#sampling) * [Tracer Provider](#tracer-provider) * [Additional Span Interfaces](#additional-span-interfaces) -* [Limits on Span Collections and Attributes](#limits-on-span-collections-and-attributes) +* [Limits on Span Collections](#limits-on-span-collections) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter) @@ -264,9 +264,7 @@ Thus, the SDK specification defines sets of possible requirements for (for example, the `Span` could be one of the parameters passed to such a function, or a getter could be provided). - - -## Limits on Span Collections and Attributes +## Limits on Span Collections Erroneous code can add unintended attributes, events, and links to a span. If these collections are unbounded, they can quickly exhaust available memory, @@ -276,18 +274,12 @@ To protect against such errors, SDK Spans MAY discard attributes, links, and events that would increase the number of elements of each collection beyond the recommended limit of 1000 elements. SDKs MAY provide a way to change this limit. -Similarly, SDKs MAY be configured to truncate attribute values. By default, attribute -values SHOULD NOT be truncated. If an SDK provides a way to set this limit and the -limit is set, then for each span attribute value, serialized into a string, -if it exceeds that limit, SDKs MUST truncate that value, so that its length -is at most equal to the limit. - If there is a configurable limit, the SDK SHOULD honor the environment variables -specified in [SDK environment variables](../sdk-environment-variables.md#span-limits). +specified in [SDK environment variables](../sdk-environment-variables.md#span-collection-limits). There SHOULD be a log emitted to indicate to the user that an attribute, event, or link was discarded due to such a limit. To prevent excessive logging, the log -should not be emitted more than once per span, attribute, event, or link. +should not be emitted once per span, or per discarded attribute, event, or links. ## Span processor From c175613d0543f0fe72f595ca129f7f90ef9b60ee Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 27 Oct 2020 20:17:37 +0100 Subject: [PATCH 09/26] Wording improvements Co-authored-by: Nikita Salnikov-Tarnovski --- specification/common/common.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 83bc21c4c8a..d194235ce6a 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -48,9 +48,9 @@ in crashes that are difficult to recover from safely. SDKs MAY be configured to truncate attribute values. By default, attribute values SHOULD NOT be truncated. If an SDK provides a way to set an attribute value size limit and the limit is set, then for each attribute value, serialized into a string, -if it exceeds that limit, SDK Spans SHOULD truncate that value, so that its length +if it exceeds that limit, SDK Spans MUST truncate that value, so that its length is at most equal to the limit. However if a serialized value does not exceed the -size limit, then it shouldn't be serialized. +size limit, then it SHOULD NOT be serialized. SDKs SHOULD choose any serialization protocol, which is performant and appropriate for the language and/or environment they are implemented in. Please note that the From 5259377322f7bc658b92c314eee6a1cedcf19e51 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Wed, 28 Oct 2020 14:20:23 +0100 Subject: [PATCH 10/26] More accurate naming for attribute truncation env variables --- specification/sdk-environment-variables.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index d20edba0fd0..e0eba4fe0ea 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -31,12 +31,12 @@ Additional values can be specified in the respective SDK's documentation, in cas ## Span Limits -| Name | Description | Default | Notes | -| ------------------------------- | ------------------------------------- | ------- | ----- | -| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 1000 | | -| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 1000 | | -| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 1000 | | -| OTEL_SPAN_ATTRIBUTE_SIZE_LIMIT | Maximum allowed span attribute length | | See notes for OTEL_ATTRIBUTE_VALUE_SIZE_LIMIT | +| Name | Description | Default | Notes | +| ------------------------------------- | ------------------------------------- | ------- | ----- | +| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 1000 | | +| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 1000 | | +| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 1000 | | +| OTEL_SPAN_ATTRIBUTE_VALUE_SIZE_LIMIT | Maximum allowed span attribute length | | See notes for OTEL_ATTRIBUTE_VALUE_SIZE_LIMIT | ## Metric Limits From 5ea1f0034b90ced744568ecd3257c1fa904229f8 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 15 Jun 2021 17:27:03 +0200 Subject: [PATCH 11/26] fix: typos --- specification/common/common.md | 1 + specification/sdk-environment-variables.md | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 683d69bebd4..7976209ee65 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -51,6 +51,7 @@ SDKs MAY be configured to truncate attribute lists and/or their values. By default, attribute lists and values SHOULD NOT be truncated. If an SDK provides a way to: + - set an attribute value length limit and the limit is set, then for each attribute value: - if it is a string, if it exceeds that limit (counting any character in it as diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 3025f94ae83..40461ee51df 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -81,8 +81,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) From 47c86a34b31fd05d06c274dc315d2ed0abc49806 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 15 Jun 2021 17:52:07 +0200 Subject: [PATCH 12/26] fix: merge mistakes --- specification/common/common.md | 4 +++- specification/metrics/sdk.md | 3 --- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 7976209ee65..8ee28067f2f 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -77,7 +77,9 @@ attributes, then it SHOULD NOT offer an unscoped (e.g. `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`, as opposed to e.g. `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`) global environment variable for such a limit. SDKs SHOULD only offer environment variables for the types of attributes, -for which that SDK implements truncation mechanism. +for which that SDK implements truncation mechanism. For each implemented limit +SDK MUST first try to use the unscoped variable, if it isn't set, only then try +to use the scoped variable. If the SDK implements the limits above, it MUST provide a way to change these limits via a configuration passed to the to the `Provider`, where `` diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 55c3e9e018a..88abc6325cd 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -152,9 +152,6 @@ Push Metric Exporter sends the data on its own schedule. Here are some examples: ### Pull Metric Exporter -TODO: T.B.D.: DDSketch considered a good choice for ValueRecorder -instrument default aggregation. - Pull Metric Exporter reacts to the metrics scrapers and reports the data passively. This pattern has been widely adopted by [Prometheus](https://prometheus.io/). From 8bd3a9bb423efa4e60273acd9ecf9a5921ea4da8 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Wed, 16 Jun 2021 13:17:57 +0200 Subject: [PATCH 13/26] fix: PR feedback --- specification/common/common.md | 25 +++------------------- specification/sdk-environment-variables.md | 9 ++++++++ 2 files changed, 12 insertions(+), 22 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 8ee28067f2f..a6384166beb 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -70,32 +70,13 @@ once per record on which an attribute is set. If a record is embedded in another record (e.g. Events within a Span), then the log SHOULD NOT be emitted more than once per parent record. -To define a limit SDKs SHOULD honor the environment variables specified in -[SDK environment variables](../sdk-environment-variables.md#attribute-limits). -If an SDK does not implement truncation mechanism for all implementations of -attributes, then it SHOULD NOT offer an unscoped (e.g. -`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`, as opposed to e.g. -`OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`) global environment variable for such a -limit. SDKs SHOULD only offer environment variables for the types of attributes, -for which that SDK implements truncation mechanism. For each implemented limit -SDK MUST first try to use the unscoped variable, if it isn't set, only then try -to use the scoped variable. - If the SDK implements the limits above, it MUST provide a way to change these -limits via a configuration passed to the to the `Provider`, where `` -is any kind of a producer of records, which implement attributes. - -The options MAY be bundled in a class, which then SHOULD be called -`Limits` (where `` is a type of a record, e.g. `Span`). Names of -the configuration options SHOULD be the same as in the list below. -Implementations MAY provide additional configuration options such as -`AttributePerEventCountLimit` or `AttributePerLinkCountLimit`. +limits programatically. Names of the configuration options SHOULD be the same as +in the list below. Implementations MAY provide additional configuration options +such as `AttributePerEventCountLimit` or `AttributePerLinkCountLimit`. **Configurable parameters:** * `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record; * `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length; - -SDKs MAY use a different notation (e.g. snake_case) if it's more suitable for -its language. diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 40461ee51df..67b48740013 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -76,6 +76,15 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b See the SDK [Attribute Limits](common/common.md#attribute-limits) section for the definition of the limits. +If an SDK does not implement truncation mechanism for all implementations of +attributes, then it SHOULD NOT offer an unscoped (e.g. +`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`, as opposed to scoped, e.g. +`OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`) global environment variable for such a +limit. SDKs SHOULD only offer environment variables for the types of attributes, +for which that SDK implements truncation mechanism. For each implemented limit +SDK MUST first try to use the unscoped variable, if it isn't set, only then try +to use the scoped variable. + | Name | Description | Default | Notes | | --------------------------------- | ------------------------------------ | ------- | ----- | | OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. | From c2ed17c7f7cfe5648557aedc32c360041eb568e9 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Wed, 16 Jun 2021 13:44:20 +0200 Subject: [PATCH 14/26] fix: typo in link --- spec-compliance-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index d1c6d8f70ff..98f86cdf7db 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -92,7 +92,7 @@ formats is required. Implementing more than one format is optional. | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .Net | Swift | |-----------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------| -| [Measurement Limits](specification/metrics/skd.md#measurement-limits) | X | | | | | | | | | | | | +| [Measurement Limits](specification/metrics/sdk.md#measurement-limits) | X | | | | | | | | | | | | ## Resource From 05173b908ba138fba9e05fc6e25d938cfbb0735d Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Mon, 21 Jun 2021 13:45:58 +0200 Subject: [PATCH 15/26] fix: PR feedback --- specification/common/common.md | 21 ++++++++++----------- specification/metrics/sdk.md | 8 +++----- specification/sdk-environment-variables.md | 9 --------- 3 files changed, 13 insertions(+), 25 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index a6384166beb..324303b27e0 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -47,8 +47,8 @@ Execution of erroneous code can result in unintended attributes. If there is no limits placed on attributes, they can quickly exhaust available memory, resulting in crashes that are difficult to recover from safely. -SDKs MAY be configured to truncate attribute lists and/or their values. By -default, attribute lists and values SHOULD NOT be truncated. +By default an SDK SHOULD apply truncation as per the list of +[configurable parameters](#attribute-limits-configuration) below. If an SDK provides a way to: @@ -61,19 +61,18 @@ If an SDK provides a way to: values separately, - otherwise a value MUST NOT be truncated; - set a limit of unique attribute keys, and the limit is set: - - for each unique attributes key which exceeds a limit, SDK MUST discard that - key/value pair. + - for each unique attributes key, addition of which would result in exceeding + the limit, SDK MUST discard that key/value pair. There SHOULD be a log emitted to indicate to the user that an attribute was -truncated. To prevent excessive logging, the log MUST NOT be emitted more than -once per record on which an attribute is set. If a record is embedded in another -record (e.g. Events within a Span), then the log SHOULD NOT be emitted more than -once per parent record. +truncated or discarded. To prevent excessive logging, the log MUST NOT be +emitted more than once per record on which an attribute is set. If a record is +embedded in another record (e.g. Events within a Span), then the log SHOULD NOT +be emitted more than once per parent record. If the SDK implements the limits above, it MUST provide a way to change these -limits programatically. Names of the configuration options SHOULD be the same as -in the list below. Implementations MAY provide additional configuration options -such as `AttributePerEventCountLimit` or `AttributePerLinkCountLimit`. +limits programmatically. Names of the configuration options SHOULD be the same as +in the list below. **Configurable parameters:** diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 88abc6325cd..40677e9706d 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -47,11 +47,9 @@ then `MeterProvider` MUST provide at least one way to configure them. ## Measurement Limits -Measurement attributes MUST adhere to the -[common rules of attribute limits](../common/common.md#attribute-limits). - -If the SDK implements the limits above it MUST provide a way to change these -limits, via a configuration to the `MeterProvider`. +Measurement attributes are exempt from the +[common rules of attribute limits](../common/common.md#attribute-limits) due to +the experimental status of the Metrics SDK specification. ## MeasurementProcessor diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 67b48740013..c6bd30552b9 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -103,15 +103,6 @@ See the SDK [Span Limits](trace/sdk.md#span-limits) section for the definition o | OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | | | OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | | -## Measurement Limits - -See the SDK [Measurement Limits](metrics/sdk.md#measurement-limits) section for the definition of the limits. - -| Name | Description | Default | Notes | -| --------------------------------------------- | ------------------------------------------- | ------- | ----- | -| OTEL_MEASUREMENT_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. | -| OTEL_MEASUREMENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed measurement attribute count | 128 | | - ## OTLP Exporter See [OpenTelemetry Protocol Exporter Configuration Options](./protocol/exporter.md). From 5b763d36fec665ba6529ab4bdcc7bf5e3247c3d4 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Mon, 21 Jun 2021 13:54:07 +0200 Subject: [PATCH 16/26] fix: PR feedback --- spec-compliance-matrix.md | 8 +++----- specification/metrics/sdk.md | 4 ---- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 98f86cdf7db..fb6cff29ecd 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -90,9 +90,9 @@ formats is required. Implementing more than one format is optional. ## Metrics -| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .Net | Swift | -|-----------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------| -| [Measurement Limits](specification/metrics/sdk.md#measurement-limits) | X | | | | | | | | | | | | +|Feature |Optional|Go|Java|JS |Python|Ruby|Erlang|PHP|Rust|C++|.Net|Swift| +|----------------------------------------------|--------|--|----|---|------|----|------|---|----|---|----|-----| +|TBD| ## Resource @@ -141,8 +141,6 @@ Note: Support for environment variables is optional. |OTEL_EXPORTER_ZIPKIN_* | - | | | | | - | - | - | - | - | - | |OTEL_TRACES_EXPORTER | - | + | | + | + | + | | - | - | | | |OTEL_METRICS_EXPORTER | - | + | | + | - | - | | - | - | - | - | -|OTEL_MEASUREMENT_ATTRIBUTE_COUNT_LIMIT | | | | | | | | | | | | -|OTEL_MEASUREMENT_ATTRIBUTE_VALUE_LENGTH_LIMIT | | | | | | | | | | | | |OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | - | + | | + | + | - | | + | - | | | |OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | | | | | | | | | | | | |OTEL_SPAN_EVENT_COUNT_LIMIT | - | + | | + | + | - | | + | - | | | diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 40677e9706d..5bef2e3c2e4 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -41,10 +41,6 @@ TODO: * Configure timing (related to [issue 1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)). -Configuration of [Measurement Limits](#measurement-limits) MUST be managed -solely by the `MeterProvider`. If Measurement Limits are implemented in an SDK, -then `MeterProvider` MUST provide at least one way to configure them. - ## Measurement Limits Measurement attributes are exempt from the From b180054bae28ed9c551ea366ff29ccd63643d76b Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Mon, 21 Jun 2021 16:56:07 +0200 Subject: [PATCH 17/26] chore: changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a25e167053..4d911afaba2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ release. ### Traces +- Add generalized attribute count and attribute value length limits and relevant + environment variables. + ([#1130](https://github.com/open-telemetry/opentelemetry-specification/pull/1130)) + ### Metrics ### Logs From cf73a3bfdee886f82d87e1a6632644657d2fa571 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Mon, 12 Jul 2021 12:02:47 +0200 Subject: [PATCH 18/26] Update specification/sdk-environment-variables.md Co-authored-by: Tyler Yahn --- specification/sdk-environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 77185beff74..55bf661fa5e 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -82,7 +82,7 @@ attributes, then it SHOULD NOT offer an unscoped (e.g. `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`) global environment variable for such a limit. SDKs SHOULD only offer environment variables for the types of attributes, for which that SDK implements truncation mechanism. For each implemented limit -SDK MUST first try to use the unscoped variable, if it isn't set, only then try +the SDK MUST first try to use the unscoped variable, if it isn't set, only then try to use the scoped variable. | Name | Description | Default | Notes | From 50556d150f90f5733149d224a01b0ce7fc2d3926 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Mon, 12 Jul 2021 12:05:58 +0200 Subject: [PATCH 19/26] Update specification/common/common.md Co-authored-by: Tyler Yahn --- specification/common/common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/common.md b/specification/common/common.md index 6b35da3467b..2ddda0111a8 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -57,7 +57,7 @@ If an SDK provides a way to: - set an attribute value length limit and the limit is set, then for each attribute value: - if it is a string, if it exceeds that limit (counting any character in it as - 1), SDK Spans MUST truncate that value, so that its length is at most equal + 1), SDKs MUST truncate that value, so that its length is at most equal to the limit, - if it is an array of strings, then apply the above rule to each of the values separately, From 89f4b3a421b1004394658e6fa21315b072c92e83 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 13 Jul 2021 15:46:36 +0200 Subject: [PATCH 20/26] fix: clarify priority of limits --- specification/common/common.md | 6 ++++++ specification/sdk-environment-variables.md | 12 +++--------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 2ddda0111a8..9dbb03de127 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -76,6 +76,12 @@ If the SDK implements the limits above, it MUST provide a way to change these limits programmatically. Names of the configuration options SHOULD be the same as in the list below. +An SDK MAY implement model-specific limits, for example +`SpanAttributeCountLimit`. If both a general and a model-specific limit are +implemented, then the SDK MUST first attempt to use the model-specific limit, if +it isn't set and doesn't have a default, then the SDK MUST attempt to use the +general limit. + **Configurable parameters:** diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 55bf661fa5e..2c6510c8c4a 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -74,16 +74,10 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b ## Attribute Limits -See the SDK [Attribute Limits](common/common.md#attribute-limits) section for the definition of the limits. +SDKs SHOULD only offer environment variables for the types of attributes, for +which that SDK implements truncation mechanism. -If an SDK does not implement truncation mechanism for all implementations of -attributes, then it SHOULD NOT offer an unscoped (e.g. -`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`, as opposed to scoped, e.g. -`OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`) global environment variable for such a -limit. SDKs SHOULD only offer environment variables for the types of attributes, -for which that SDK implements truncation mechanism. For each implemented limit -the SDK MUST first try to use the unscoped variable, if it isn't set, only then try -to use the scoped variable. +See the SDK [Attribute Limits](common/common.md#attribute-limits) section for the definition of the limits. | Name | Description | Default | Notes | | --------------------------------- | ------------------------------------ | ------- | ----- | From f428739be5c1bf450182f3f243076bd4e37605c4 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Sat, 17 Jul 2021 16:04:35 +0200 Subject: [PATCH 21/26] fix: nerf logging requirements --- specification/common/common.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 9dbb03de127..306674cb1a6 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -66,11 +66,9 @@ If an SDK provides a way to: - for each unique attributes key, addition of which would result in exceeding the limit, SDK MUST discard that key/value pair. -There SHOULD be a log emitted to indicate to the user that an attribute was +There SHOULD NOT be a log emitted to indicate to the user that an attribute was truncated or discarded. To prevent excessive logging, the log MUST NOT be -emitted more than once per record on which an attribute is set. If a record is -embedded in another record (e.g. Events within a Span), then the log SHOULD NOT -be emitted more than once per parent record. +emitted more than once per record on which an attribute is set. If the SDK implements the limits above, it MUST provide a way to change these limits programmatically. Names of the configuration options SHOULD be the same as From 6f9992a51bea7a85df3f703ac24250bb69b5d4f7 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 20 Jul 2021 10:29:57 +0200 Subject: [PATCH 22/26] fix: grammar --- specification/common/common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/common.md b/specification/common/common.md index 306674cb1a6..b847dcf9a40 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -45,7 +45,7 @@ See [Attribute Naming](attribute-naming.md) for naming guidelines. ### Attribute Limits -Execution of erroneous code can result in unintended attributes. If there is no +Execution of erroneous code can result in unintended attributes. If there are no limits placed on attributes, they can quickly exhaust available memory, resulting in crashes that are difficult to recover from safely. From e3d7b737f6711615c5098b3e5a3aa4c3ffe327ce Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 27 Jul 2021 13:15:17 +0200 Subject: [PATCH 23/26] Fixes from Yuri Co-authored-by: Yuri Shkuro --- specification/common/common.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index b847dcf9a40..9518a9362d2 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -54,7 +54,7 @@ By default an SDK SHOULD apply truncation as per the list of If an SDK provides a way to: -- set an attribute value length limit and the limit is set, then for each +- set an attribute value length limit such that for each attribute value: - if it is a string, if it exceeds that limit (counting any character in it as 1), SDKs MUST truncate that value, so that its length is at most equal @@ -62,11 +62,11 @@ If an SDK provides a way to: - if it is an array of strings, then apply the above rule to each of the values separately, - otherwise a value MUST NOT be truncated; -- set a limit of unique attribute keys, and the limit is set: +- set a limit of unique attribute keys such that: - for each unique attributes key, addition of which would result in exceeding the limit, SDK MUST discard that key/value pair. -There SHOULD NOT be a log emitted to indicate to the user that an attribute was +There MAY be a log emitted to indicate to the user that an attribute was truncated or discarded. To prevent excessive logging, the log MUST NOT be emitted more than once per record on which an attribute is set. From 243b07deb690d43b76d2d43c634925b4b87f25ad Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 27 Jul 2021 13:52:51 +0200 Subject: [PATCH 24/26] fix: clarify metrics exemption --- specification/common/common.md | 7 +++++++ specification/metrics/sdk.md | 9 +++++---- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 9518a9362d2..724ef5da03e 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -9,6 +9,7 @@ Table of Contents - [Attributes](#attributes) - [Attribute Limits](#attribute-limits) + - [Exempt Entities](#exempt-entities) @@ -85,3 +86,9 @@ general limit. * `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record; * `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length; + +#### Exempt Entities + +Attributes which belong to Metrics MUST NOT implement the aforementioned +limits at ths time as discussed in +[Metrics Attribute Limits](../metrics/sdk.md#attribute-limits). diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 5bef2e3c2e4..e98c55b6afb 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -41,11 +41,12 @@ TODO: * Configure timing (related to [issue 1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)). -## Measurement Limits +## Attribute Limits -Measurement attributes are exempt from the -[common rules of attribute limits](../common/common.md#attribute-limits) due to -the experimental status of the Metrics SDK specification. +Attributes which belong to Metrics MUST NOT implement limits from the +[common rules of attribute limits](../common/common.md#attribute-limits) at this +time. Attribute truncation or deletion could affect identitity of metric time +series and it requires further analysis. ## MeasurementProcessor From cd51664b8a0339a249bfdd242d6f2d73f0c03864 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 27 Jul 2021 14:05:49 +0200 Subject: [PATCH 25/26] fix: link --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index e98c55b6afb..dd42ad3a769 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -23,7 +23,7 @@ Table of Contents * [MeterProvider](#meterprovider) -* [Measurement Limits](#measurement-limits) +* [Attribute Limits](#attribute-limits) * [MeasurementProcessor](#measurementprocessor) * [MetricProcessor](#metricprocessor) * [MetricExporter](#metricexporter) From ff664a271570d89fae99379aa48e0dd31bfd2de3 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Tue, 27 Jul 2021 16:31:42 +0200 Subject: [PATCH 26/26] fix: language --- specification/common/common.md | 4 ++-- specification/metrics/sdk.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 724ef5da03e..6cb26c12f99 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -89,6 +89,6 @@ general limit. #### Exempt Entities -Attributes which belong to Metrics MUST NOT implement the aforementioned -limits at ths time as discussed in +Attributes, which belong to Metrics, are exempt from the limits described above +at this time, as discussed in [Metrics Attribute Limits](../metrics/sdk.md#attribute-limits). diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index dd42ad3a769..0d80945ebb5 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -43,7 +43,7 @@ TODO: ## Attribute Limits -Attributes which belong to Metrics MUST NOT implement limits from the +Attributes which belong to Metrics are exempt from the [common rules of attribute limits](../common/common.md#attribute-limits) at this time. Attribute truncation or deletion could affect identitity of metric time series and it requires further analysis.