Skip to content

Commit 5503915

Browse files
tigrannajaryantigrannajaryan
committed
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.
1 parent fa19ac9 commit 5503915

File tree

5 files changed

+24
-9
lines changed

5 files changed

+24
-9
lines changed

‎CHANGELOG.md

+3
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ release.
2929

3030
### Common
3131

32+
- Support maps and heterogeneous arrays as attribute values
33+
([#2888](https://github.com/open-telemetry/opentelemetry-specification/pull/2888))
34+
3235
## v1.18.0 (2023-02-09)
3336

3437
### Context

‎spec-compliance-matrix.md

+3
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ formats is required. Implementing more than one format is optional.
6363
| Double floating-point type | | + | + | + | + | + | + | - | + | + | + | + |
6464
| Signed int64 type | | + | + | + | + | + | + | - | + | + | + | + |
6565
| Array of primitives (homogeneous) | | + | + | + | + | + | + | + | + | + | + | + |
66+
| Non-homogeneous arrays and maps (including nested) | | | | | | | | | | | | |
6667
| `null` values documented as invalid/undefined | | + | + | + | + | + | N/A | + | | + | | N/A |
6768
| Unicode support for keys and string values | | + | + | + | + | + | + | + | + | + | + | + |
6869
| [Span linking](specification/trace/api.md#specifying-links) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
@@ -206,6 +207,7 @@ formats is required. Implementing more than one format is optional.
206207
| The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation. | | | + | | - | | | | | | - | |
207208
| The metrics SDK provides an `ExemplarFilter` interface or extension point. | X | | - | | - | | | + | | | - | |
208209
| An `ExemplarFilter` has access to the measurement value, attributes, `Context` and timestamp. | X | | - | | - | | | + | | | - | |
210+
| Non-homogeneous arrays and maps (including nested) | | | | | | | | | | | | |
209211

210212
## Logs
211213

@@ -234,6 +236,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
234236
| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
235237
|---------------------------------------------------------------------------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------|
236238
| Create from Attributes | | + | + | + | + | + | + | + | + | + | + | + |
239+
| Non-homogeneous arrays and maps (including nested) for attribute values | | | | | | | | | | | | |
237240
| Create empty | | + | + | + | + | + | + | + | + | + | + | + |
238241
| [Merge (v2)](specification/resource/sdk.md#merge) | | + | + | | + | + | + | + | + | + | + | |
239242
| Retrieve attributes | | + | + | + | + | + | + | + | + | + | + | + |

‎specification/common/README.md

+14-5
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,21 @@ aliases: [/docs/reference/specification/common/common]
2727
An `Attribute` is a key-value pair, which MUST have the following properties:
2828

2929
- The attribute key MUST be a non-`null` and non-empty string.
30-
- The attribute value is either:
30+
- The attribute value can be of `any` type, where any is defined as one of the following:
3131
- A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer.
32-
- An array of primitive type values. The array MUST be homogeneous,
33-
i.e., it MUST NOT contain values of different types.
34-
35-
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 `[]`.
32+
- A homogeneous array of values of primitive type [before 1.19.0].
33+
- An array of `any` values [since 1.19.0].
34+
- A key/value map, where key is string and value is `any` value [since 1.19.0].
35+
36+
Complex attribute types (such as homogenous arrays, arrays of any, and maps) SHOULD be
37+
used sparingly, in situations where their use minimizes manipulation of the data’s
38+
original structure.
39+
40+
When exporting to protocols that do not natively support a particular non-string
41+
value type the value should be converted to a string JSON-encoding of the value.
42+
43+
For example, the expression `int64(100)` will be encoded as `100`, `float64(1.5)` will
44+
be encoded as `1.5`, and an empty array of any type will be encoded as `[]`.
3645

3746
Attribute values expressing a numerical value of zero, an empty string, or an
3847
empty array are considered meaningful and MUST be stored and passed on to

‎specification/trace/sdk_exporters/jaeger.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -134,8 +134,8 @@ OpenTelemetry Span `Attribute`(s) MUST be reported as `tags` to Jaeger.
134134

135135
Primitive types MUST be represented by the corresponding types of Jaeger tags.
136136

137-
Array values MUST be serialized to string like a JSON list as mentioned in
138-
[semantic conventions](../../overview.md#semantic-conventions).
137+
Array and map values MUST be serialized to a JSON and recorded as a tag of string type
138+
as mentioned in [attribute value definition](../../common/README.md#attribute).
139139

140140
### Links
141141

‎specification/trace/sdk_exporters/zipkin.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,8 @@ document maps to the strongly-typed fields of Zipkin spans.
123123
Primitive types MUST be converted to string using en-US culture settings.
124124
Boolean values MUST use lower case strings `"true"` and `"false"`.
125125

126-
Array values MUST be serialized to string like a JSON list as mentioned in
127-
[semantic conventions](../../overview.md#semantic-conventions).
126+
Array and map values MUST be serialized to a JSON and recorded as a tag of string type
127+
as mentioned in [attribute value definition](../../common/README.md#attribute).
128128

129129
TBD: add examples
130130

0 commit comments

Comments
 (0)