diff --git a/.gitignore b/.gitignore index 71d4b9f93cc..adb2dd9d1cf 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,6 @@ internal/tools/bin # Node.js files for tools (e.g. markdown-toc) node_modules/ package-lock.json + +#Visual Studio +.vs/ \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c9077e2dc5..671c6ec182f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -103,6 +103,8 @@ release. - Clarify that Scope is defined at build time ([#2878](https://github.com/open-telemetry/opentelemetry-specification/pull/2878)) +- Clarify Attribute Value definition to match Protobuf AnyValue implementation + ([#2581](https://github.com/open-telemetry/opentelemetry-specification/issues/2581)) ## v1.14.0 (2022-10-04) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 6ef0a29f209..4d72b5002d4 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) | | + | + | + | + | + | + | + | + | + | + | + | +| `nested` Attribute value | x | | | + | | | | | | | | | | `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) | | | | | | | | | | | | | diff --git a/specification/common/README.md b/specification/common/README.md index 2b377a731cd..7725d640048 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -31,6 +31,9 @@ An `Attribute` is a key-value pair, which MUST have the following properties: - 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. + - It MAY also contain another valid Attribute value resulting in `nested` Attributes + and the referenced Attribute MUST not be recursive. i.e. The value of the + key-value pair will itself be a key-value pair. 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 `[]`. @@ -52,6 +55,17 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). +`nested` Attribute support MAY be protocol, signal, language, SDK or Exporter +specific as not all SDKs, exporters or backends support the storing or sending +of a hierarchy of Attributes. In those cases they SHOULD implement a strategy to +handle how nested Attributes are stored or transmitted, like using a JSON-encoded +string value as highlighted for protocols above. The depth of the any resulting +hierarchy SHOULD be limited and MUST not include recursive references. + +`nested` Attributes are also how consumers MAY provide custom attributes that +are domain specific and have no defined semantic conventions beyond the specific +name used for the signal. + See [Attribute Naming](attribute-naming.md) for naming guidelines. See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines. @@ -81,6 +95,13 @@ If an SDK provides a way to: - set a limit of unique attribute keys such that: - for each unique attribute key, addition of which would result in exceeding the limit, SDK MUST discard that key/value pair. +- set a limit on the supported depth of nested attributes: + - when this limit is exceeded it MAY provide a configurable strategy for handling + items beyond this limit which MAY include: + - Dropping the excessive depth, + - Replacing the value with a relevant token indicating values have been truncated, + - Converted to a string representation, which MUST also comply with the value + length limits; There MAY be a log emitted to indicate to the user that an attribute was truncated or discarded. To prevent excessive logging, the log MUST NOT be @@ -101,6 +122,7 @@ followed by the global limit default value. * `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record; * `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length; +* `AttributeNestedLengthLimit` (Default=10; if supported) - Maximum allowed number of nested attribute value; #### Exempt Entities @@ -147,3 +169,8 @@ Some other implementations may use a streaming approach where every that individual attribute value being exported using a streaming wire protocol. In such cases the enforcement of uniqueness will likely be the responsibility of the recipient of this data. + +An Attribute Collection does not infer a hierarchy or `nested` collection of +Attributes, it represents a single flat definition which MAY be represented +logically as an array, list, set or map as `nested` Attributes support is +provided by the Attribute Value.