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 Nov 30, 2022
1 parent 0a4c665 commit 477df7f
Show file tree
Hide file tree
Showing 5 changed files with 22 additions and 14 deletions.
10 changes: 3 additions & 7 deletions CHANGELOG.md
View file
Expand Up @@ -47,6 +47,9 @@ release.

### Common

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

## v1.15.0 (2022-11-09)

### Context
Expand Down Expand Up @@ -109,17 +112,10 @@ release.

### SDK Configuration

- No changes.

### Telemetry Schemas

- No changes.

### Common

- 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
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) | | | | | | | | | | | | |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 | | + | + | + | + | + | + | + | + | + | + | + |
Expand Down
15 changes: 12 additions & 3 deletions specification/common/README.md
View file
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions specification/trace/sdk_exporters/jaeger.md
View file
Expand Up @@ -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

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 477df7f

Please sign in to comment.