Support maps and heterogeneous arrays as attribute values

Resolves open-telemetry#376 Use cases where this is necessary or useful: 1. Specify more than one resource in the telemetry: open-telemetry#579 2. Data coming from external source, e.g. AWS Metadata: open-telemetry#596 (comment) or open-telemetry#376 (comment) 3. Capturing HTTP headers: open-telemetry#376 (comment) 4. Structured stack traces: open-telemetry#2841 5. Payloads as attributes: open-telemetry/oteps#219 (comment) This is a draft PR to see what the change looks like. If this PR is merged it will be nice to follow it up with: - A standard way of flattening maps and nested objects when converting from OTLP to formats that don't support maps/nested objects. - Recommendations for semantic conventions to use/not use complex objects.
tigrannajaryan · Nov 30, 2022 · d8a488d · d8a488d
1 parent 0a4c665
commit d8a488d
Show file tree

Hide file tree

Showing 5 changed files with 24 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -47,6 +47,9 @@ release.
 
 ### Common
 
+- Support maps and heterogeneous arrays as attribute values
+  ([#2888](https://github.com/open-telemetry/opentelemetry-specification/pull/2888))
+
 ## v1.15.0 (2022-11-09)
 
 ### Context
@@ -110,7 +113,7 @@ release.
 ### SDK Configuration
 
 - No changes.
-
+ 
 ### Telemetry Schemas
 
 - No changes.
@@ -119,7 +122,7 @@ release.
 
 - Clarify that Scope is defined at build time
   ([#2878](https://github.com/open-telemetry/opentelemetry-specification/pull/2878))
-
+ 
 ## v1.14.0 (2022-10-04)
 
 ### Context

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -63,6 +63,7 @@ formats is required. Implementing more than one format is optional.
 | Double floating-point type                                                                       |          | +   | +    | +   | +      | +    | +      | -   | +    | +   | +    | +     |
 | Signed int64 type                                                                                |          | +   | +    | +   | +      | +    | +      | -   | +    | +   | +    | +     |
 | Array of primitives (homogeneous)                                                                |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
+| Non-homogeneous arrays and maps (including nested)                                               |          |     |      |     |        |      |        |     |      |     |      |       |
 | `null` values documented as invalid/undefined                                                    |          | +   | +    | +   | +      | +    | N/A    | +   |      | +   |      | N/A   |
 | Unicode support for keys and string values                                                       |          | +   | +    | +   | +      | +    | +      | +   | +    | +   | +    | +     |
 | [Span linking](specification/trace/api.md#specifying-links)                                      |          |     |      |     |        |      |        |     |      |     |      |       |
@@ -205,6 +206,7 @@ formats is required. Implementing more than one format is optional.
 | The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation.                               |          |     | +    |     | -      |      |        |     |      |     | -    |       |
 | The metrics SDK provides an `ExemplarFilter` interface or extension point.                                                                                             | X        |     | -    |     | -      |      |        |     |      |     | -    |       |
 | An `ExemplarFilter` has access to the measurement value, attributes, `Context` and timestamp.                                                                          | X        |     | -    |     | -      |      |        |     |      |     | -    |       |
+| Non-homogeneous arrays and maps (including nested)                                                                                                                     |          |     |      |     |        |      |        |     |      |     |      |       |
 
 ## Logs
 
@@ -233,6 +235,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
 | Feature                                                                                                                                     | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
 |---------------------------------------------------------------------------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------|
 | Create from Attributes                                                                                                                      |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
+| Non-homogeneous arrays and maps (including nested) for attribute values                                                                     |          |    |      |    |        |      |        |     |      |     |      |       |
 | Create empty                                                                                                                                |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | [Merge (v2)](specification/resource/sdk.md#merge)                                                                                           |          | +  | +    |    | +      | +    | +      | +   | +    | +   | +    |       |
 | Retrieve attributes                                                                                                                         |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |

diff --git a/specification/common/README.md b/specification/common/README.md
@@ -29,10 +29,19 @@ An `Attribute` is a key-value pair, which MUST have the following properties:
 - The attribute key MUST be a non-`null` and non-empty string.
 - The attribute value is either:
   - 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.
+  - A homogeneous array of values of primitive type.
+  - An array of any attribute values [since 1.15.0].
+  - A key/value map, where key is string and value is any attribute value [since 1.15.0].
 
-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 `[]`.
+When exporting to protocols that do not natively support a particular non-string
+value type the following conversion SHOULD be performed:
+
+| OpenTelemetry Value Type                               | Convert To String          |
+|--------------------------------------------------------|----------------------------|
+| boolean, floating point, integer, array, key/value map | JSON-encoding of the value |
+
+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

diff --git a/specification/trace/sdk_exporters/jaeger.md b/specification/trace/sdk_exporters/jaeger.md
@@ -133,8 +133,8 @@ OpenTelemetry Span `Attribute`(s) MUST be reported as `tags` to Jaeger.
 
 Primitive types MUST be represented by the corresponding types of Jaeger tags.
 
-Array values MUST be serialized to string like a JSON list as mentioned in
-[semantic conventions](../../overview.md#semantic-conventions).
+Array and map values MUST be serialized to a JSON and recorded as a tag of string type
+as mentioned in [attribute value definition](../../common/README.md#attribute).
 
 ### Links
 

diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md
@@ -123,8 +123,8 @@ document maps to the strongly-typed fields of Zipkin spans.
 Primitive types MUST be converted to string using en-US culture settings.
 Boolean values MUST use lower case strings `"true"` and `"false"`.
 
-Array values MUST be serialized to string like a JSON list as mentioned in
-[semantic conventions](../../overview.md#semantic-conventions).
+Array and map values MUST be serialized to a JSON and recorded as a tag of string type
+as mentioned in [attribute value definition](../../common/README.md#attribute).
 
 TBD: add examples