[Common] Clarify Attribute support based on stable wire protocol definition of Attributes #2581

.gitignore

@@ -28,3 +28,6 @@ internal/tools/bin
 # Node.js files for tools (e.g. markdown-toc)
 node_modules/
 package-lock.json
+
+#Visual Studio
+.vs/

CHANGELOG.md

@@ -178,6 +178,8 @@ release.
 
 - Clarify that Scope is defined at build time
   ([#2878](https://github.com/open-telemetry/opentelemetry-specification/pull/2878))
+- Clarify Attribute Value definition to match Protobuf AnyValue implementation
+  ([#2581](https://github.com/open-telemetry/opentelemetry-specification/issues/2581))
 
 ## v1.14.0 (2022-10-04)
 

specification/common/README.md

@@ -14,6 +14,7 @@ aliases: [/docs/reference/specification/common/common]
   * [Attribute Limits](#attribute-limits)
     + [Configurable Parameters](#configurable-parameters)
     + [Exempt Entities](#exempt-entities)
+  * [Nested Attributes](#nested-attributes)
 - [Attribute Collections](#attribute-collections)
 
 <!-- tocstop -->
@@ -31,8 +32,15 @@ An `Attribute` is a key-value pair, which MUST have the following properties:
   - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer.
   - An array of primitive type values. The array MUST be homogeneous,
     i.e., it MUST NOT contain values of different types.
+  - When specified via semantic conventions it MAY (see [Nested Attributes](#nested-attributes))
+    contain another valid Attribute value resulting in `nested` Attributes. Any
+    referenced Attribute MUST not be recursive. i.e. The value of the
+    key-value pair will itself be a key-value pair.
 
-For protocols that do not natively support non-string values, non-string values SHOULD be represented as JSON-encoded strings.  For example, the expression `int64(100)` will be encoded as `100`, `float64(1.5)` will be encoded as `1.5`, and an empty array of any type will be encoded as `[]`.
+For protocols that do not natively support non-string values, non-string values
+SHOULD be represented as JSON-encoded strings.  For example, the expression
+`int64(100)` will be encoded as `100`, `float64(1.5)` will be encoded as `1.5`,
+and an empty array of any type will be encoded as `[]`.
 
 Attribute values expressing a numerical value of zero, an empty string, or an
 empty array are considered meaningful and MUST be stored and passed on to
@@ -52,6 +60,8 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va
 both containing an array of strings to represent a mapping
 `header_keys[i] -> header_values[i]`).
 
+See [Nested Attribute](#nested-attributes) for defined support
+
 See [Attribute Naming](attribute-naming.md) for naming guidelines.
 
 See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines.
@@ -116,6 +126,24 @@ Attributes, which belong to Metrics, are exempt from the limits described above
 at this time, as discussed in
 [Metrics Attribute Limits](../metrics/sdk.md#attribute-limits).
 
+### Nested Attributes
+
+While `nested` attributes are supported at the [protocol level](https://github.com/open-telemetry/opentelemetry-proto/blob/157bedf2d42bd2c2c9a35e355839a48f99ce06ee/opentelemetry/proto/common/v1/common.proto#L28-L67)
+for the `KeyValueList` via `AnyValue` this does not infer that `nested` attributes
+are supported for every protocol, signal, language, SDK or Exporter.
+
+Support for `nested` attributes are defined by general semantic conventions, if
+a `nested` attribute is received for an unsupported area it may be ignored and
+not propagated.
+
+| Area                 | Supported  |
+|----------------------|------------|
+| Span                 | no         |
+| Metrics              | no         |
+| Logs                 | yes        |
+| Scopes               | no         |
+| Resources            | no         |
+
 ## Attribute Collections
 
 [Resources](../resource/sdk.md), Metrics
@@ -147,3 +175,7 @@ Some other implementations may use a streaming approach where every
 that individual attribute value being exported using a streaming wire protocol.
 In such cases the enforcement of uniqueness will likely be the responsibility of
 the recipient of this data.
+
+An Attribute Collection does not infer a hierarchy or `nested` collection of
+Attributes. A Collection represents a single flat definition which MAY be
+represented logically as an array, list, set or map of Attribute Values.

specification/common/mapping-to-non-otlp.md

@@ -93,3 +93,12 @@ This key-value pair should only be recorded when it contains a non-zero value.
 Exporters to formats that don't have a concept that is equivalent to the Scope
 SHOULD record the attributes at the most suitable place in their corresponding format,
 typically at the Span, Metric or LogRecord equivalent.
+
+### Nested Attributes
+
+Only certain protocols, languages, SDKs or Exporter support the storing or sending
+of a hierarchy of Attributes. When not supported in those cases they SHOULD
+implement a strategy to handle how nested Attributes are stored or transmitted,
+like using a JSON-encoded string value as highlighted for protocols above. The
+depth of the any resulting hierarchy SHOULD be limited and MUST not include
+recursive references.