Skip to content

Commit 13e1fb1

Browse files
authored
chore: reorder sections in common/README.md (#4711)
Fixes #4709 Reorder the sections in `common/README.md`. I think that the the following orgniazation is more natural: ``` - AnyValue * map - Attribute * Attribute Collections - Attribute Limits * Configurable Parameters * Exempt Entities ``` than ``` - AnyValue * map - Attribute * Attribute Limits + Configurable Parameters + Exempt Entities - Attribute Collections ``` Especially that "Attribute Limits" describes the limits also for the Attribute Collections.
1 parent 59d702f commit 13e1fb1

File tree

1 file changed

+52
-52
lines changed

1 file changed

+52
-52
lines changed

specification/common/README.md

Lines changed: 52 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@ path_base_for_github_subdir:
1818
- [AnyValue](#anyvalue)
1919
* [map](#mapstring-anyvalue)
2020
- [Attribute](#attribute)
21-
* [Attribute Limits](#attribute-limits)
22-
+ [Configurable Parameters](#configurable-parameters)
23-
+ [Exempt Entities](#exempt-entities)
24-
- [Attribute Collections](#attribute-collections)
21+
* [Attribute Collections](#attribute-collections)
22+
- [Attribute Limits](#attribute-limits)
23+
* [Configurable Parameters](#configurable-parameters)
24+
* [Exempt Entities](#exempt-entities)
2525

2626
<!-- tocstop -->
2727

@@ -111,7 +111,52 @@ See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/b
111111
See [this document](attribute-type-mapping.md) to find out how to map values obtained
112112
outside OpenTelemetry into OpenTelemetry attribute values.
113113

114-
### Attribute Limits
114+
### Attribute Collections
115+
116+
[Resources](../resource/sdk.md),
117+
[Instrumentation Scopes](instrumentation-scope.md),
118+
[Metric points](../metrics/data-model.md#metric-points),
119+
[Spans](../trace/api.md#set-attributes), Span
120+
[Events](../trace/api.md#add-events), Span
121+
[Links](../trace/api.md#link) and
122+
[Log Records](../logs/data-model.md),
123+
contain a collection of attributes.
124+
125+
Implementation MUST by default ensure that the exported attribute collections
126+
contain only unique keys. The enforcement of uniqueness may be performed
127+
in a variety of ways as it best fits the limitations of the particular
128+
implementation.
129+
130+
Normally for the telemetry generated using OpenTelemetry SDKs the attribute
131+
key-value pairs are set via an API that either accepts a single key-value pair
132+
or a collection of key-value pairs. Setting an attribute with the same key as an
133+
existing attribute SHOULD overwrite the existing attribute's value. See for
134+
example Span's [SetAttribute](../trace/api.md#set-attributes) API.
135+
136+
A typical implementation of [SetAttribute](../trace/api.md#set-attributes) API
137+
will enforce the uniqueness by overwriting any existing attribute values pending
138+
to be exported, so that when the Span is eventually exported the exporters see
139+
only unique attributes. The OTLP format in particular requires that exported
140+
Resources, Spans, Metric data points and Log Records contain only unique
141+
attributes.
142+
143+
Some other implementations may use a streaming approach where every
144+
[SetAttribute](../trace/api.md#set-attributes) API call immediately results in
145+
that individual attribute value being exported using a streaming wire protocol.
146+
In such cases the enforcement of uniqueness will likely be the responsibility of
147+
the recipient of this data.
148+
149+
Implementations MAY have an option to allow exporting attribute collections
150+
with duplicate keys (e.g. for better performance).
151+
If such option is provided, it MUST be documented that for many receivers,
152+
handling of maps with duplicate keys is unpredictable and it is the users'
153+
responsibility to ensure keys are not duplicate.
154+
155+
Collection of attributes are equal when they contain the same attributes,
156+
irrespective of the order in which those elements appear
157+
(unordered collection equality).
158+
159+
## Attribute Limits
115160

116161
Execution of erroneous code can result in unintended attributes. If there are no
117162
limits placed on attribute collections, they can quickly exhaust available memory,
@@ -165,12 +210,12 @@ Note that the limits apply only to attribute collections.
165210
Therefore, they do not apply to values within other data structures such as
166211
[`LogRecord.Body`](../logs/data-model.md#field-body).
167212

168-
#### Configurable Parameters
213+
### Configurable Parameters
169214

170215
* `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record;
171216
* `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length (applies to string values and byte arrays);
172217

173-
#### Exempt Entities
218+
### Exempt Entities
174219

175220
Resource attributes SHOULD be exempt from the limits described above as resources
176221
are not susceptible to the scenarios (auto-instrumentation) that result in
@@ -183,48 +228,3 @@ attribute limits for Resources.
183228
Attributes, which belong to Metrics, are exempt from the limits described above
184229
at this time, as discussed in
185230
[Metrics Attribute Limits](../metrics/sdk.md#attribute-limits).
186-
187-
## Attribute Collections
188-
189-
[Resources](../resource/sdk.md),
190-
[Instrumentation Scopes](instrumentation-scope.md),
191-
[Metric points](../metrics/data-model.md#metric-points),
192-
[Spans](../trace/api.md#set-attributes), Span
193-
[Events](../trace/api.md#add-events), Span
194-
[Links](../trace/api.md#link) and
195-
[Log Records](../logs/data-model.md),
196-
contain a collection of attributes.
197-
198-
Implementation MUST by default ensure that the exported attribute collections
199-
contain only unique keys. The enforcement of uniqueness may be performed
200-
in a variety of ways as it best fits the limitations of the particular
201-
implementation.
202-
203-
Normally for the telemetry generated using OpenTelemetry SDKs the attribute
204-
key-value pairs are set via an API that either accepts a single key-value pair
205-
or a collection of key-value pairs. Setting an attribute with the same key as an
206-
existing attribute SHOULD overwrite the existing attribute's value. See for
207-
example Span's [SetAttribute](../trace/api.md#set-attributes) API.
208-
209-
A typical implementation of [SetAttribute](../trace/api.md#set-attributes) API
210-
will enforce the uniqueness by overwriting any existing attribute values pending
211-
to be exported, so that when the Span is eventually exported the exporters see
212-
only unique attributes. The OTLP format in particular requires that exported
213-
Resources, Spans, Metric data points and Log Records contain only unique
214-
attributes.
215-
216-
Some other implementations may use a streaming approach where every
217-
[SetAttribute](../trace/api.md#set-attributes) API call immediately results in
218-
that individual attribute value being exported using a streaming wire protocol.
219-
In such cases the enforcement of uniqueness will likely be the responsibility of
220-
the recipient of this data.
221-
222-
Implementations MAY have an option to allow exporting attribute collections
223-
with duplicate keys (e.g. for better performance).
224-
If such option is provided, it MUST be documented that for many receivers,
225-
handling of maps with duplicate keys is unpredictable and it is the users'
226-
responsibility to ensure keys are not duplicate.
227-
228-
Collection of attributes are equal when they contain the same attributes,
229-
irrespective of the order in which those elements appear
230-
(unordered collection equality).

0 commit comments

Comments
 (0)