Skip to content

Commit 7cef355

Browse files
jtmalinowskijtmalinowski
authored
Add an option to limit length of values of attributes and metric values (#1130)
1 parent c35c212 commit 7cef355

File tree

6 files changed

+93
-17
lines changed

6 files changed

+93
-17
lines changed

‎CHANGELOG.md

+4
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ release.
1111

1212
### Traces
1313

14+
- Add generalized attribute count and attribute value length limits and relevant
15+
environment variables.
16+
([#1130](https://github.com/open-telemetry/opentelemetry-specification/pull/1130))
17+
- Adding environment variables for event and link attribute limits. ([#1751](https://github.com/open-telemetry/opentelemetry-specification/pull/1751))
1418
- Adding SDK configuration for Jaeger remote sampler ([#1791](https://github.com/open-telemetry/opentelemetry-specification/pull/1791))
1519

1620
### Metrics

‎spec-compliance-matrix.md

+4
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ formats is required. Implementing more than one format is optional.
7979
| [IdGenerators](specification/trace/sdk.md#id-generators) | | + | + | | + | + | | | + | + | | + |
8080
| [SpanLimits](specification/trace/sdk.md#span-limits) | X | + | + | | + | + | | | | - | | + |
8181
| [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) | | | | | + | + | | | + | + | | |
82+
| [Attribute Limits](specification/common/common.md#attribute-limits) | X | | | | | | | | | | | |
8283

8384
## Baggage
8485

@@ -141,12 +142,15 @@ Note: Support for environment variables is optional.
141142
|OTEL_TRACES_EXPORTER | - | + | | + | + | + | | - | - | | |
142143
|OTEL_METRICS_EXPORTER | - | + | | + | - | - | | - | - | - | - |
143144
|OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | - | + | | + | + | - | | + | - | | |
145+
|OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | | | | | | | | | | | |
144146
|OTEL_SPAN_EVENT_COUNT_LIMIT | - | + | | + | + | - | | + | - | | |
145147
|OTEL_SPAN_LINK_COUNT_LIMIT | - | + | | + | + | - | | + | - | | |
146148
|OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | | | | | | | | | | | |
147149
|OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | | | | | | | | | | | |
148150
|OTEL_TRACES_SAMPLER | - | + | | + | + | + | | - | - | | |
149151
|OTEL_TRACES_SAMPLER_ARG | - | + | | + | + | + | | - | - | | |
152+
|OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | | | | | | | | | | | |
153+
|OTEL_ATTRIBUTE_COUNT_LIMIT | | | | | | | | | | | |
150154

151155
## Exporters
152156

‎specification/common/common.md

+51
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ Table of Contents
88
</summary>
99

1010
- [Attributes](#attributes)
11+
- [Attribute Limits](#attribute-limits)
12+
- [Exempt Entities](#exempt-entities)
1113

1214
</details>
1315

@@ -41,3 +43,52 @@ both containing an array of strings to represent a mapping
4143
`header_keys[i] -> header_values[i]`).
4244

4345
See [Attribute Naming](attribute-naming.md) for naming guidelines.
46+
47+
### Attribute Limits
48+
49+
Execution of erroneous code can result in unintended attributes. If there are no
50+
limits placed on attributes, they can quickly exhaust available memory, resulting
51+
in crashes that are difficult to recover from safely.
52+
53+
By default an SDK SHOULD apply truncation as per the list of
54+
[configurable parameters](#attribute-limits-configuration) below.
55+
56+
If an SDK provides a way to:
57+
58+
- set an attribute value length limit such that for each
59+
attribute value:
60+
- if it is a string, if it exceeds that limit (counting any character in it as
61+
1), SDKs MUST truncate that value, so that its length is at most equal
62+
to the limit,
63+
- if it is an array of strings, then apply the above rule to each of the
64+
values separately,
65+
- otherwise a value MUST NOT be truncated;
66+
- set a limit of unique attribute keys such that:
67+
- for each unique attributes key, addition of which would result in exceeding
68+
the limit, SDK MUST discard that key/value pair.
69+
70+
There MAY be a log emitted to indicate to the user that an attribute was
71+
truncated or discarded. To prevent excessive logging, the log MUST NOT be
72+
emitted more than once per record on which an attribute is set.
73+
74+
If the SDK implements the limits above, it MUST provide a way to change these
75+
limits programmatically. Names of the configuration options SHOULD be the same as
76+
in the list below.
77+
78+
An SDK MAY implement model-specific limits, for example
79+
`SpanAttributeCountLimit`. If both a general and a model-specific limit are
80+
implemented, then the SDK MUST first attempt to use the model-specific limit, if
81+
it isn't set and doesn't have a default, then the SDK MUST attempt to use the
82+
general limit.
83+
84+
<a name="attribute-limits-configuration"></a>
85+
**Configurable parameters:**
86+
87+
* `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record;
88+
* `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length;
89+
90+
#### Exempt Entities
91+
92+
Attributes, which belong to Metrics, are exempt from the limits described above
93+
at this time, as discussed in
94+
[Metrics Attribute Limits](../metrics/sdk.md#attribute-limits).

‎specification/metrics/sdk.md

+8
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Table of Contents
2323
</summary>
2424

2525
* [MeterProvider](#meterprovider)
26+
* [Attribute Limits](#attribute-limits)
2627
* [MeasurementProcessor](#measurementprocessor)
2728
* [MetricProcessor](#metricprocessor)
2829
* [MetricExporter](#metricexporter)
@@ -207,6 +208,13 @@ meter_provider
207208
.set_exporter(ConsoleExporter())
208209
```
209210

211+
## Attribute Limits
212+
213+
Attributes which belong to Metrics are exempt from the
214+
[common rules of attribute limits](../common/common.md#attribute-limits) at this
215+
time. Attribute truncation or deletion could affect identitity of metric time
216+
series and it requires further analysis.
217+
210218
## MeasurementProcessor
211219

212220
`MeasurementProcessor` is an interface which allows hooks when a

‎specification/sdk-environment-variables.md

+21-8
Original file line numberDiff line numberDiff line change
@@ -78,19 +78,32 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b
7878
| OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | |
7979
| OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE |
8080

81-
## Span Collection Limits
81+
## Attribute Limits
82+
83+
SDKs SHOULD only offer environment variables for the types of attributes, for
84+
which that SDK implements truncation mechanism.
85+
86+
See the SDK [Attribute Limits](common/common.md#attribute-limits) section for the definition of the limits.
87+
88+
| Name | Description | Default | Notes |
89+
| --------------------------------- | ------------------------------------ | ------- | ----- |
90+
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. |
91+
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | |
92+
93+
## Span Limits <a name="span-collection-limits"></a>
8294

8395
**Status**: [Stable](document-status.md)
8496

8597
See the SDK [Span Limits](trace/sdk.md#span-limits) section for the definition of the limits.
8698

87-
| Name | Description | Default | Notes |
88-
| -------------------------------- | ---------------------------------------------- | ------- | ----- |
89-
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | |
90-
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | |
91-
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | |
92-
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | |
93-
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | |
99+
| Name | Description | Default | Notes |
100+
| -------------------------------------- | ---------------------------------------------- | ------- | ----- |
101+
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. |
102+
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | |
103+
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | |
104+
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | |
105+
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | |
106+
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | |
94107

95108
## OTLP Exporter
96109

‎specification/trace/sdk.md

+5-9
Original file line numberDiff line numberDiff line change
@@ -319,20 +319,16 @@ Optional parameters:
319319

320320
## Span Limits
321321

322-
Erroneous code can add unintended attributes, events, and links to a span. If
323-
these collections are unbounded, they can quickly exhaust available memory,
324-
resulting in crashes that are difficult to recover from safely.
322+
Span attributes MUST adhere to the [common rules of attribute limits](../common/common.md#attribute-limits).
325323

326-
To protect against such errors, SDK Spans MAY discard attributes, links, and
327-
events that would increase the number of elements of each collection beyond
328-
the configured limit.
324+
SDK Spans MAY also discard links and events that would increase the number of
325+
elements of each collection beyond the configured limit.
329326

330327
If the SDK implements the limits above it MUST provide a way to change these
331328
limits, via a configuration to the TracerProvider, by allowing users to
332329
configure individual limits like in the Java example bellow.
333330

334-
The name of the configuration options SHOULD be `AttributeCountLimit`,
335-
`EventCountLimit` and `LinkCountLimit`. The options MAY be bundled in a class,
331+
The name of the configuration options SHOULD be `EventCountLimit` and `LinkCountLimit`. The options MAY be bundled in a class,
336332
which then SHOULD be called `SpanLimits`. Implementations MAY provide additional
337333
configuration such as `AttributePerEventCountLimit` and `AttributePerLinkCountLimit`.
338334

@@ -354,7 +350,7 @@ public final class SpanLimits {
354350

355351
**Configurable parameters:**
356352

357-
* `AttributeCountLimit` (Default=128) - Maximum allowed span attribute count;
353+
* [all common options applicable to attributes](../common/common.md#attribute-limits-configuration)
358354
* `EventCountLimit` (Default=128) - Maximum allowed span event count;
359355
* `LinkCountLimit` (Default=128) - Maximum allowed span link count;
360356
* `AttributePerEventCountLimit` (Default=128) - Maximum allowed attribute per span event count;

0 commit comments

Comments
 (0)