From 6f520dceff9f225b350d148dcdf072910674c968 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 9 Feb 2021 11:20:11 -0800 Subject: [PATCH] Finalize SpanLimits definition, add option to configure it Signed-off-by: Bogdan Drutu --- CHANGELOG.md | 1 + specification/sdk-environment-variables.md | 4 ++- specification/trace/sdk.md | 42 ++++++++++++++++++---- 3 files changed, 39 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f5f81d853a..7e78276304d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ New: - Add `cloud.infrastructure_service` resource attribute ([#1112](https://github.com/open-telemetry/opentelemetry-specification/pull/1112)) +- Add `SpanLimits` as a configuration for the TracerProvider([#1416](https://github.com/open-telemetry/opentelemetry-specification/pull/1416)) Updates: diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 5cbe2a7bf6a..19bb034cd9e 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -73,7 +73,9 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b ## Span Collection Limits -**Status**: [Experimental](document-status.md) +**Status**: [Stable](document-status.md) + +See the SDK [Span Limits](trace/sdk.md#span-limits) section for the definition of the limits. | Name | Description | Default | Notes | | ------------------------------- | ------------------------------------ | ------- | ----- | diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 0e37d6328cc..6be251d5e5d 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -9,7 +9,7 @@ * [Tracer Provider](#tracer-provider) * [Additional Span Interfaces](#additional-span-interfaces) * [Sampling](#sampling) -* [Limits on Span Collections](#limits-on-span-collections) +* [Span Limits](#span-limits) * [Id Generator](#id-generators) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter) @@ -26,9 +26,10 @@ supplied to the `TracerProvider` must be used to create an [`InstrumentationLibrary`][otep-83] instance which is stored on the created `Tracer`. -Configuration (i.e., [Span processors](#span-processor), [IdGenerator](#id-generators), -and [`Sampler`](#sampling)) MUST be managed solely by the `TracerProvider` and it -MUST provide some way to configure them, at least when creating or initializing it. +Configuration (i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators), +[SpanLimits](#span-limits) and [`Sampler`](#sampling)) MUST be managed solely by +the `TracerProvider` and it MUST provide some way to configure them, at least +when creating or initializing it. The TracerProvider MAY provide methods to update the configuration. If configuration is updated (e.g., adding a `SpanProcessor`), @@ -292,7 +293,7 @@ Optional parameters: |present|false|true|`localParentSampled()`| |present|false|false|`localParentNotSampled()`| -## Limits on Span Collections +## Span Limits Erroneous code can add unintended attributes, events, and links to a span. If these collections are unbounded, they can quickly exhaust available memory, @@ -300,9 +301,36 @@ resulting in crashes that are difficult to recover from safely. 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. +the recommended limit of 1000 elements. -If there is a configurable limit, the SDK SHOULD honor the environment variables +The SDKs MUST provide a way to change these limits, via a configuration to the +TracerProvider, by allowing users to configure individual limits like the java +example bellow. The name of the cofiguration class MAY be `SpanLimits`, and the +name of the properties SHOULD be `AttributeCountLimit`, `EventCountLimit`, +`LinkCountLimit`. Implementation MAY provide additional configuration such as +`AttributePerEventCountLimit`, `AttributePerLinkCountLimit`. + +```java +public final class SpanLimits { + SpanLimits(int attributeCountLimit, int linkCountLimit, int eventCountLimit); + + public int getAttributeCountLimit(); + + public int getEventCountLimit(); + + public int getLinkCountLimit(); +} +``` + +**Configurable parameters:** + +* `AttributeCountLimit` - Maximum allowed span attribute count; +* `EventCountLimit` - Maximum allowed span event count; +* `LinkCountLimit` - Maximum allowed span link count; +* `AttributePerEventCountLimit` - Maximum allowed attribute per span event count; +* `AttributePerLinkCountLimit` - Maximum allowed attribute per span link count; + +If there is a configurable provided, the SDK SHOULD honor the environment variables 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,