Skip to content

Commit

Permalink
Support maps and heterogeneous arrays as attribute values
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@tigrannajaryan
tigrannajaryan committed Feb 14, 2023
1 parent fa19ac9 commit 5503915
Show file tree
Hide file tree
Showing 5 changed files with 24 additions and 9 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Expand Up @@ -29,6 +29,9 @@ release.

### Common

- Support maps and heterogeneous arrays as attribute values
([#2888](https://github.com/open-telemetry/opentelemetry-specification/pull/2888))

## v1.18.0 (2023-02-09)

### Context
Expand Down
3 changes: 3 additions & 0 deletions spec-compliance-matrix.md
View file
Expand Up @@ -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) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
Expand Down Expand Up @@ -206,6 +207,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

Expand Down Expand Up @@ -234,6 +236,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 | | + | + | + | + | + | + | + | + | + | + | + |
Expand Down
19 changes: 14 additions & 5 deletions specification/common/README.md
View file
Expand Up @@ -27,12 +27,21 @@ aliases: [/docs/reference/specification/common/common]
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:
- The attribute value can be of `any` type, where any is defined as one of the following:
- 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.

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 `[]`.
- A homogeneous array of values of primitive type [before 1.19.0].
- An array of `any` values [since 1.19.0].
- A key/value map, where key is string and value is `any` value [since 1.19.0].

Complex attribute types (such as homogenous arrays, arrays of any, and maps) SHOULD be
used sparingly, in situations where their use minimizes manipulation of the data’s
original structure.

When exporting to protocols that do not natively support a particular non-string
value type the value should be converted to a string 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
Expand Down
4 changes: 2 additions & 2 deletions specification/trace/sdk_exporters/jaeger.md
View file
Expand Up @@ -134,8 +134,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

Expand Down
4 changes: 2 additions & 2 deletions specification/trace/sdk_exporters/zipkin.md
View file
Expand Up @@ -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

Expand Down

0 comments on commit 5503915

Please sign in to comment.