From d8a488dfbeb0d346458b01ea93ead087283c5c7e Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 17 Oct 2022 17:44:11 -0400 Subject: [PATCH] Support maps and heterogeneous arrays as attribute values Resolves https://github.com/open-telemetry/opentelemetry-specification/issues/376 Use cases where this is necessary or useful: 1. Specify more than one resource in the telemetry: https://github.com/open-telemetry/opentelemetry-specification/issues/579 2. Data coming from external source, e.g. AWS Metadata: https://github.com/open-telemetry/opentelemetry-specification/pull/596#issuecomment-628983680 or https://github.com/open-telemetry/opentelemetry-specification/issues/376#issuecomment-1227501082 3. Capturing HTTP headers: https://github.com/open-telemetry/opentelemetry-specification/issues/376#issuecomment-908493520 4. Structured stack traces: https://github.com/open-telemetry/opentelemetry-specification/pull/2841 5. Payloads as attributes: https://github.com/open-telemetry/oteps/pull/219#discussion_r971065645 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. --- CHANGELOG.md | 7 +++++-- spec-compliance-matrix.md | 3 +++ specification/common/README.md | 15 ++++++++++++--- specification/trace/sdk_exporters/jaeger.md | 4 ++-- specification/trace/sdk_exporters/zipkin.md | 4 ++-- 5 files changed, 24 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 06a9acd224e..23c47ca0dae 100644 --- 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 index 6ef0a29f209..07e7c8ebe96 100644 --- 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 index 2b377a731cd..0c1eb50c0be 100644 --- 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 index 629adbb011e..aff3a94e551 100644 --- 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 index b398c1efa31..755bd38e03a 100644 --- 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