Skip to content

Commit

Permalink
Finalize SpanLimits definition, add option to configure it (open-tele…
Browse files Browse the repository at this point in the history
…metry#1416)

* Finalize SpanLimits definition, add option to configure it

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Address some of the feedback

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Update default for limits per event and link

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Add entry to the spec matrix

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Fix last feedback, allow this to be a class or not

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Mark span-limits optional in the compliance matrix

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>
  • Loading branch information
bogdandrutu authored Feb 10, 2021
1 parent a23aeae commit 04304d5
Show file tree
Hide file tree
Showing 4 changed files with 40 additions and 9 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
1 change: 1 addition & 0 deletions spec-compliance-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ status of the feature is not known.
| ShouldSample gets full parent Context | | | + | + | + | + | + | | | + | - | + |
| [New Span ID created also for non-recording Spans](specification/trace/sdk.md#sdk-span-creation) | | | | | + | + | | | | | - | + |
| [IdGenerators](specification/trace/sdk.md#id-generators) ] | | | | | | | | | | | | |
| [SpanLimits](specification/trace/sdk.md#span-limits) ] | X | | | | | | | | | | | |

## Baggage

Expand Down
4 changes: 3 additions & 1 deletion specification/sdk-environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| ------------------------------- | ------------------------------------ | ------- | ----- |
Expand Down
43 changes: 35 additions & 8 deletions specification/trace/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 all of them that
are implemented in the SDK, 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`),
Expand Down Expand Up @@ -292,18 +293,44 @@ 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,
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 128 elements. SDKs MAY provide a way to change this limit.
the configured 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).
It the SDK implements the limits above it MUST provide a way to change these
limits, via a configuration to the TracerProvider, by allowing users to
configure individual limits like in the Java example bellow.

The name of the configuration options SHOULD be `AttributeCountLimit`,
`EventCountLimit` and `LinkCountLimit`. The options MAY be bundled in a class,
which then SHOULD be called `SpanLimits`. Implementations MAY provide additional
configuration such as `AttributePerEventCountLimit` and `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` (Default=1000) - Maximum allowed span attribute count;
* `EventCountLimit` (Default=1000) - Maximum allowed span event count;
* `LinkCountLimit` (Default=1000) - Maximum allowed span link count;
* `AttributePerEventCountLimit` (Default=128) - Maximum allowed attribute per span event count;
* `AttributePerLinkCountLimit` (Default=128) - Maximum allowed attribute per span link count;

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
Expand Down

0 comments on commit 04304d5

Please sign in to comment.