@@ -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
111111See [ this document] ( attribute-type-mapping.md ) to find out how to map values obtained
112112outside 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
116161Execution of erroneous code can result in unintended attributes. If there are no
117162limits placed on attribute collections, they can quickly exhaust available memory,
@@ -165,12 +210,12 @@ Note that the limits apply only to attribute collections.
165210Therefore, 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
175220Resource attributes SHOULD be exempt from the limits described above as resources
176221are not susceptible to the scenarios (auto-instrumentation) that result in
@@ -183,48 +228,3 @@ attribute limits for Resources.
183228Attributes, which belong to Metrics, are exempt from the limits described above
184229at 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