diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f826d6abb2..caa7b924c00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,6 +60,8 @@ release. ([#4560](https://github.com/open-telemetry/opentelemetry-specification/pull/4560)) - ⚠️ **IMPORTANT**: Extending the set of standard attribute value types is no longer a breaking change. ([#4614](https://github.com/open-telemetry/opentelemetry-specification/pull/4614)) +- Extend the set of attribute value types to support more complex data structures. + ([#4651](https://github.com/open-telemetry/opentelemetry-specification/pull/4651)) ### OTEPs diff --git a/oteps/4485-extending-attributes-to-support-complex-values.md b/oteps/4485-extending-attributes-to-support-complex-values.md index 737c03732d4..d19b94a5f4e 100644 --- a/oteps/4485-extending-attributes-to-support-complex-values.md +++ b/oteps/4485-extending-attributes-to-support-complex-values.md @@ -94,7 +94,7 @@ extending the standard attributes provides a more seamless and user-friendly API Currently, the SDK specification has a clause that says extending the set of standard attribute would be -[considered a breaking change](/specification/common/README.md#standard-attribute). +[considered a breaking change](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.44.0/specification/common/README.md#standard-attribute). We believe that removing this clause and extending standard attributes can be done gracefully across the OpenTelemetry ecosystem @@ -123,24 +123,7 @@ Existing APIs that create or add attributes will be extended to support It's RECOMMENDED to expose an `AnyValue` type - the API representing complex or simple attribute value for type checking, ergonomics, and performance reasons. -Exposing multiple types of attribute sets is NOT RECOMMENDED, such as having "ExtendedAttributes" in addition to "Attributes". - -OTel API MUST support setting complex attributes on spans, logs, profiles, -span links, and as descriptive entity attributes. - -OTel API MAY support setting complex attributes on metrics, resources, -instrumentation scope, span events, and as identifying entity attributes. - -> [!NOTE] -> "MAY" is used here instead of "MUST" to give flexibility to dynamically -> typed language APIs since there are no concrete use cases at this time -> requiring complex attributes in these areas. -> -> Most likely statically typed languages will choose to support -> setting complex attributes uniformly everywhere. -> -> This requirement level could change from "MAY" to "MUST" in the future -> if we uncover use cases for complex attributes in these areas. +OTel API MUST support setting complex attributes. API documentation and spec language around complex attributes SHOULD include language similar to this: @@ -152,22 +135,7 @@ language similar to this: ### SDK -OTel SDK MUST support setting complex attributes on spans, logs, profiles, -span links, and as descriptive entity attributes. - -OTel SDK MAY support setting complex attributes on metrics, exemplars, resources, -instrumentation scope, span events, and as identifying entity attributes. - -> [!NOTE] -> "MAY" is used here instead of "MUST" to give flexibility to dynamically -> typed language SDKs since there are no concrete use cases at this time -> requiring complex attributes in these areas. -> -> Most likely statically typed languages will choose to support -> setting complex attributes uniformly everywhere. -> -> This requirement level could change from "MAY" to "MUST" in the future -> if we uncover use cases for complex attributes in these areas. +OTel SDK MUST support setting complex attributes. The SDK MUST support reading and modifying complex attributes during processing whenever they are allowed on the API surface. diff --git a/oteps/entities/0256-entities-data-model.md b/oteps/entities/0256-entities-data-model.md index 51d5a00faae..70d0fde0b5f 100644 --- a/oteps/entities/0256-entities-data-model.md +++ b/oteps/entities/0256-entities-data-model.md @@ -139,7 +139,7 @@ MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.

Follows any +href="https://github.com/open-telemetry/opentelemetry-specification/blob/v1.44.0/specification/logs/data-model.md#type-any">any value definition in the OpenTelemetry spec - it can be a scalar value, byte array, an array or map of values. Arbitrary deep nesting of values for arrays and maps is allowed. @@ -682,7 +682,7 @@ There are a couple of reasons: ### Attribute Data Type The data model requires the Attributes field to use the extended -[any](../../specification/logs/data-model.md#type-any) +[any](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.44.0/specification/logs/data-model.md#type-any) attribute values, that allows more complex data types. This is different from the data type used by the Id field, which is more restricted in the shape. diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 16dfda4c378..7c55ce696a1 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -199,7 +199,6 @@ Disclaimer: this list of features is still a work in progress, please refer to t | LoggerProvider.Shutdown | | | + | | + | + | | + | | + | - | | | LoggerProvider.ForceFlush | | | + | | + | + | | + | | + | - | | | Logger.Emit(LogRecord) | | | + | | + | + | | + | | + | - | | -| Reuse Standard Attributes | X | + | | | | | | | | | | | | LogRecord.Set EventName | | + | | | | | | | + | + | | | | Logger.Enabled | X | + | | | | | | + | + | + | | | | SimpleLogRecordProcessor | | | + | | + | + | | + | | + | | | diff --git a/spec-compliance-matrix/cpp.yaml b/spec-compliance-matrix/cpp.yaml index 14e20252911..bbb91260975 100644 --- a/spec-compliance-matrix/cpp.yaml +++ b/spec-compliance-matrix/cpp.yaml @@ -357,8 +357,6 @@ sections: status: '+' - name: Logger.Emit(LogRecord) status: '+' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '+' - name: Logger.Enabled diff --git a/spec-compliance-matrix/dotnet.yaml b/spec-compliance-matrix/dotnet.yaml index 7e5004b911a..c250553d05b 100644 --- a/spec-compliance-matrix/dotnet.yaml +++ b/spec-compliance-matrix/dotnet.yaml @@ -357,8 +357,6 @@ sections: status: '-' - name: Logger.Emit(LogRecord) status: '-' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/erlang.yaml b/spec-compliance-matrix/erlang.yaml index 2ff35d5dc18..483278379cc 100644 --- a/spec-compliance-matrix/erlang.yaml +++ b/spec-compliance-matrix/erlang.yaml @@ -357,8 +357,6 @@ sections: status: '?' - name: Logger.Emit(LogRecord) status: '?' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/go.yaml b/spec-compliance-matrix/go.yaml index 9fb04a6c5a8..86ebb1bfe17 100644 --- a/spec-compliance-matrix/go.yaml +++ b/spec-compliance-matrix/go.yaml @@ -357,8 +357,6 @@ sections: status: '?' - name: Logger.Emit(LogRecord) status: '?' - - name: Reuse Standard Attributes - status: '+' - name: LogRecord.Set EventName status: '+' - name: Logger.Enabled diff --git a/spec-compliance-matrix/java.yaml b/spec-compliance-matrix/java.yaml index 0e0c2b8e8d7..aa896871a54 100644 --- a/spec-compliance-matrix/java.yaml +++ b/spec-compliance-matrix/java.yaml @@ -357,8 +357,6 @@ sections: status: '+' - name: Logger.Emit(LogRecord) status: '+' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/js.yaml b/spec-compliance-matrix/js.yaml index 55e2d0152d7..a522a69f438 100644 --- a/spec-compliance-matrix/js.yaml +++ b/spec-compliance-matrix/js.yaml @@ -357,8 +357,6 @@ sections: status: '?' - name: Logger.Emit(LogRecord) status: '?' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/php.yaml b/spec-compliance-matrix/php.yaml index 2cd9a7aad6c..564f33216ba 100644 --- a/spec-compliance-matrix/php.yaml +++ b/spec-compliance-matrix/php.yaml @@ -357,8 +357,6 @@ sections: status: '+' - name: Logger.Emit(LogRecord) status: '+' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/python.yaml b/spec-compliance-matrix/python.yaml index 11a70239ed0..4c26ef34258 100644 --- a/spec-compliance-matrix/python.yaml +++ b/spec-compliance-matrix/python.yaml @@ -357,8 +357,6 @@ sections: status: '+' - name: Logger.Emit(LogRecord) status: '+' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/ruby.yaml b/spec-compliance-matrix/ruby.yaml index 5bcb784c831..908140e2064 100644 --- a/spec-compliance-matrix/ruby.yaml +++ b/spec-compliance-matrix/ruby.yaml @@ -357,8 +357,6 @@ sections: status: '+' - name: Logger.Emit(LogRecord) status: '+' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/rust.yaml b/spec-compliance-matrix/rust.yaml index 41ed148b9d7..7c2203ab5af 100644 --- a/spec-compliance-matrix/rust.yaml +++ b/spec-compliance-matrix/rust.yaml @@ -357,8 +357,6 @@ sections: status: '?' - name: Logger.Emit(LogRecord) status: '?' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '+' - name: Logger.Enabled diff --git a/spec-compliance-matrix/swift.yaml b/spec-compliance-matrix/swift.yaml index 73e78097f45..9bca50a7242 100644 --- a/spec-compliance-matrix/swift.yaml +++ b/spec-compliance-matrix/swift.yaml @@ -357,8 +357,6 @@ sections: status: '?' - name: Logger.Emit(LogRecord) status: '?' - - name: Reuse Standard Attributes - status: '?' - name: LogRecord.Set EventName status: '?' - name: Logger.Enabled diff --git a/spec-compliance-matrix/template.yaml b/spec-compliance-matrix/template.yaml index 26240de7d26..6b1a464dee4 100644 --- a/spec-compliance-matrix/template.yaml +++ b/spec-compliance-matrix/template.yaml @@ -234,8 +234,6 @@ sections: - name: LoggerProvider.Shutdown - name: LoggerProvider.ForceFlush - name: Logger.Emit(LogRecord) - - name: Reuse Standard Attributes - optional: true - name: LogRecord.Set EventName - name: Logger.Enabled optional: true diff --git a/specification/common/README.md b/specification/common/README.md index 82f634d5dc9..b92155f552a 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -8,50 +8,59 @@ path_base_for_github_subdir: # Common specification concepts -**Status**: [Stable](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified

Table of Contents +- [AnyValue](#anyvalue) + * [map](#mapstring-anyvalue) - [Attribute](#attribute) - * [Standard Attribute](#standard-attribute) - * [Attribute Limits](#attribute-limits) - + [Configurable Parameters](#configurable-parameters) - + [Exempt Entities](#exempt-entities) -- [Attribute Collections](#attribute-collections) + * [Attribute Collections](#attribute-collections) +- [Attribute Limits](#attribute-limits) + * [Configurable Parameters](#configurable-parameters) + * [Exempt Entities](#exempt-entities)
-## Attribute +## AnyValue - +`AnyValue` is either: -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, +- a homogeneous array of primitive type values. A homogeneous array MUST NOT + contain values of different types. +- **Status**: [Development](../document-status.md) - a byte array. +- **Status**: [Development](../document-status.md) - an array of `AnyValue`, +- **Status**: [Development](../document-status.md) - a [`map`](#mapstring-anyvalue), +- **Status**: [Development](../document-status.md) - an empty value if supported by the language, + (e.g. `null`, `undefined` in JavaScript/TypeScript, `None` in Python, `nil` in Go/Ruby, not supported in Erlang, etc.) -- The attribute key MUST be a non-`null` and non-empty string. - - Case sensitivity of keys is preserved. Keys that differ in casing are treated as distinct keys. -- 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. +Arbitrary deep nesting of values for arrays and maps is allowed (essentially +allows to represent an equivalent of a JSON object). -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 `[]`. +APIs SHOULD be documented in a way to communicate to users that using array and +map values may carry higher performance overhead compared to primitive values. -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 -processors / exporters. +For protocols that do not natively support some of the value types, corresponding 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 `[]`. -Attribute values of `null` are not valid and attempting to set a `null` value is -undefined behavior. +AnyValues expressing an empty value, a numerical value of zero, an empty string, +or an empty array are considered meaningful and MUST be stored and passed on to +processors / exporters. -`null` values SHOULD NOT be allowed in arrays. However, if it is impossible to -make sure that no `null` values are accepted +While `null` is a valid attribute value, its use within homogeneous arrays +SHOULD generally be avoided unless language constraints make this impossible. +However, if it is impossible to make sure that no `null` values are accepted (e.g. in languages that do not have appropriate compile-time type checking), -`null` values within arrays MUST be preserved as-is (i.e., passed on to span +`null` values within arrays MUST be preserved as-is (i.e., passed on to processors / exporters as `null`). If exporters do not support exporting `null` values, they MAY replace those values by 0, `false`, or empty strings. This is required for map/dictionary structures represented as two arrays with @@ -59,6 +68,37 @@ 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]`). +### map + +**Status**: [Development](../document-status.md) + +`map` is a map of string keys to `AnyValue` values. +The keys in the map are unique (duplicate keys are not allowed). + +The representation of the map is language-dependent. + +The implementation MUST by default ensure that the exported maps contain only unique keys. + +The implementation MAY have an option to allow exporting maps with duplicate keys +(e.g. for better performance). +If such option is provided, it MUST be documented that for many receivers, +handling of maps with duplicate keys is unpredictable and it is the users' +responsibility to ensure keys are not duplicate. + +Maps are equal when they contain the same key-value pairs, +irrespective of the order in which those elements appear +(unordered collection equality). + +## Attribute + + + +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. + - Case sensitivity of keys is preserved. Keys that differ in casing are treated as distinct keys. +- The attribute value MUST be one of types defined in [AnyValue](#anyvalue). + Attributes are equal when their keys and values are equal. See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/naming.md#attributes) for naming guidelines. @@ -68,26 +108,56 @@ See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/b See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. -### Standard Attribute +### Attribute Collections -Attributes are used in various places throughout the OpenTelemetry data model. -We designate the [previous attribute section](#attribute) as the standard -attribute definition, in order to facilitate more intuitive and consistent API / -SDK design. +[Resources](../resource/sdk.md), +[Instrumentation Scopes](instrumentation-scope.md), +[Metric points](../metrics/data-model.md#metric-points), +[Spans](../trace/api.md#set-attributes), Span +[Events](../trace/api.md#add-events), Span +[Links](../trace/api.md#link) and +[Log Records](../logs/data-model.md), +contain a collection of attributes. -The standard attribute definition SHOULD be used to represent attributes in data -modeling unless there is a strong justification to diverge. For example, the Log -Data Model has an extended [attributes](../logs/data-model.md#field-attributes) -definition allowing values of [type `Any`](../logs/data-model.md#type-any). This -reflects that LogRecord attributes are expected to model data produced from -external log APIs, which do not necessarily have the same value type -restrictions as the standard attribute definition. +Implementation MUST by default ensure that the exported attribute collections +contain only unique keys. The enforcement of uniqueness may be performed +in a variety of ways as it best fits the limitations of the particular +implementation. -### Attribute Limits +Normally for the telemetry generated using OpenTelemetry SDKs the attribute +key-value pairs are set via an API that either accepts a single key-value pair +or a collection of key-value pairs. Setting an attribute with the same key as an +existing attribute SHOULD overwrite the existing attribute's value. See for +example Span's [SetAttribute](../trace/api.md#set-attributes) API. + +A typical implementation of [SetAttribute](../trace/api.md#set-attributes) API +will enforce the uniqueness by overwriting any existing attribute values pending +to be exported, so that when the Span is eventually exported the exporters see +only unique attributes. The OTLP format in particular requires that exported +Resources, Spans, Metric data points and Log Records contain only unique +attributes. + +Some other implementations may use a streaming approach where every +[SetAttribute](../trace/api.md#set-attributes) API call immediately results in +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. + +Implementations MAY have an option to allow exporting attribute collections +with duplicate keys (e.g. for better performance). +If such option is provided, it MUST be documented that for many receivers, +handling of maps with duplicate keys is unpredictable and it is the users' +responsibility to ensure keys are not duplicate. + +Collection of attributes are equal when they contain the same attributes, +irrespective of the order in which those elements appear +(unordered collection equality). + +## Attribute Limits Execution of erroneous code can result in unintended attributes. If there are no -limits placed on attributes, they can quickly exhaust available memory, resulting -in crashes that are difficult to recover from safely. +limits placed on attribute collections, they can quickly exhaust available memory, +resulting in crashes that are difficult to recover from safely. By default an SDK SHOULD apply truncation as per the list of [configurable parameters](#configurable-parameters) below. @@ -99,12 +169,24 @@ If an SDK provides a way to: - if it is a string, if it exceeds that limit (counting any character in it as 1), SDKs MUST truncate that value, so that its length is at most equal to the limit, - - if it is an array of strings, then apply the above rule to each of the - values separately, + - **Status**: [Development](../document-status.md) - if it is a byte array, + if its length exceeds that limit (counting each byte as 1), + SDKs MUST truncate that value, so that its length is at most equal to the limit, + - if it is an array of strings, then apply the limit to + each value within the array separately, + - **Status**: [Development](../document-status.md) - if it is an array of [AnyValue](#anyvalue), + then apply the limit to each element of the array separately (and recursively), + - **Status**: [Development](../document-status.md) - if it is a [map](#mapstring-anyvalue), + then apply the limit to each value within the map separately (and recursively), - otherwise a value MUST NOT be truncated; -- 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 an attribute count limit such that: + - if adding an attribute to an attribute collection would result + in exceeding the limit (counting each attribute in the collection as 1), + the SDK MUST discard that attribute, so that the total number of attributes in + an attribute collection is at most equal to the limit; + - the count limit applies only to top-level attributes, not to nested key-value + pairs within [maps](#mapstring-anyvalue); + - otherwise an attribute MUST NOT be discarded. 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 @@ -121,12 +203,16 @@ use the model-specific limit, if it isn't set, then the SDK MUST attempt to use the general limit. If neither are defined, then the SDK MUST try to use the model-specific limit default value, followed by the global limit default value. -#### Configurable Parameters +Note that the limits apply only to attributes collections. +Therefore, they do not apply to values within other data structures such as +[`LogRecord.Body`](../logs/data-model.md#field-body). + +### Configurable Parameters * `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record; -* `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length; +* `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length (applies to string values and byte arrays); -#### Exempt Entities +### Exempt Entities Resource attributes SHOULD be exempt from the limits described above as resources are not susceptible to the scenarios (auto-instrumentation) that result in @@ -139,40 +225,3 @@ attribute limits for Resources. Attributes, which belong to Metrics, are exempt from the limits described above at this time, as discussed in [Metrics Attribute Limits](../metrics/sdk.md#attribute-limits). - -## Attribute Collections - -[Resources](../resource/sdk.md), -[Instrumentation Scopes](instrumentation-scope.md), -[Metric points](../metrics/data-model.md#metric-points), -[Spans](../trace/api.md#set-attributes), Span -[Events](../trace/api.md#add-events), Span -[Links](../trace/api.md#link) and -[Log Records](../logs/data-model.md) may contain a collection of attributes. The -keys in each such collection are unique, i.e. there MUST NOT exist more than one -key-value pair with the same key. The enforcement of uniqueness may be performed -in a variety of ways as it best fits the limitations of the particular -implementation. - -Normally for the telemetry generated using OpenTelemetry SDKs the attribute -key-value pairs are set via an API that either accepts a single key-value pair -or a collection of key-value pairs. Setting an attribute with the same key as an -existing attribute SHOULD overwrite the existing attribute's value. See for -example Span's [SetAttribute](../trace/api.md#set-attributes) API. - -A typical implementation of [SetAttribute](../trace/api.md#set-attributes) API -will enforce the uniqueness by overwriting any existing attribute values pending -to be exported, so that when the Span is eventually exported the exporters see -only unique attributes. The OTLP format in particular requires that exported -Resources, Spans, Metric data points and Log Records contain only unique -attributes. - -Some other implementations may use a streaming approach where every -[SetAttribute](../trace/api.md#set-attributes) API call immediately results in -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. - -Collection of attributes are equal when they contain the same attributes, -irrespective of the order in which those elements appear -(unordered collection equality). diff --git a/specification/entities/data-model.md b/specification/entities/data-model.md index 22c277edd82..4c7c088657c 100644 --- a/specification/entities/data-model.md +++ b/specification/entities/data-model.md @@ -48,8 +48,8 @@ physical format and encoding of how entity data is recorded). | Field | Type | Description | |--------------|----------------------------------------|-----------------| | Type | string | Defines the type of the entity. MUST not change during the lifetime of the entity. For example: "service" or "host". This field is required and MUST not be empty for valid entities. | -| Id | map | Attributes that identify the entity.

MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

Follows OpenTelemetry [Standard attribute definition](../common/README.md#standard-attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attributes. | -| Description | map | Descriptive (non-identifying) attributes of the entity.

MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.

Follows [any](../logs/data-model.md#type-any) value definition in the OpenTelemetry spec. Arbitrary deep nesting of values for arrays and maps is allowed.

SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) for attributes. | +| Id | map | Attributes that identify the entity.

MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions) for attributes. | +| Description | map | Descriptive (non-identifying) attributes of the entity.

MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity's identity.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). SHOULD follow OpenTelemetry [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md) for attributes. | ## Minimally Sufficient Identity diff --git a/specification/logs/api.md b/specification/logs/api.md index 977770be6fb..66eb9c6b995 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -6,7 +6,7 @@ aliases: [bridge-api] # Logs API -**Status**: [Stable](../document-status.md), except where otherwise specified +**Status**: [Stable](../document-status.md)

Table of Contents @@ -124,14 +124,6 @@ The API MUST accept the following parameters: - [Attributes](./data-model.md#field-attributes) (optional) - [Event Name](./data-model.md#field-eventname) (optional) -**Status**: [Development](../document-status.md) - -The API SHOULD provide functionality for users to convert -[Standard Attributes](../common/README.md#standard-attribute) -so they can be used, or directly accept them, in the log signal. -This allows the reuse of [Standard Attributes](../common/README.md#standard-attribute) -across signals. - ### Enabled To help users avoid performing computationally expensive operations when diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 807e5899aa1..6893df5c1cb 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -430,14 +430,15 @@ when it is used to represent an unspecified severity. ### Field: `Body` -Type: [`any`](#type-any). +Type: [`any`](#type-any) or [AnyValue](../common/README.md#anyvalue). Description: A value containing the body of the log record. Can be for example a human-readable string message (including multi-line) describing the event in a free form or it can be a structured data composed of arrays and maps of other -values. Body MUST support [`any` type](#type-any) to preserve the semantics of -structured logs emitted by the applications. Can vary for each occurrence of the -event coming from the same source. This field is optional. +values. Body MUST support [AnyValue](../common/README.md#anyvalue) +to preserve the semantics of structured logs emitted by the applications. +Can vary for each occurrence of the event coming from the same source. +This field is optional. ### Field: `Resource` @@ -464,15 +465,12 @@ they all have the same value of `InstrumentationScope`. This field is optional. ### Field: `Attributes` -Type: [`map`](#type-mapstring-any). +Type: [`map`](#type-mapstring-any) or [Attribute Collection](../common/README.md#attribute-collections). Description: Additional information about the specific event occurrence. Unlike the `Resource` field, which is fixed for a particular source, `Attributes` can vary for each occurrence of the event coming from the same source. Can contain information about the request context (other than [Trace Context Fields](#trace-context-fields)). -The log attribute model MUST support [`any` type](#type-any), -a superset of [standard Attribute](../common/README.md#attribute), -to preserve the semantics of structured attributes emitted by the applications. This field is optional. #### Errors and Exceptions diff --git a/specification/resource/data-model.md b/specification/resource/data-model.md index 60b924ddebb..6a9d579dc07 100644 --- a/specification/resource/data-model.md +++ b/specification/resource/data-model.md @@ -24,8 +24,8 @@ running in a container on Kubernetes, which is associated to a Pod running on a Node that is a VM but also is in a namespace and possibly is part of a Deployment. Resource could have attributes to denote information about the Container, the Pod, the Node, the VM or the Deployment. All of these help -identify what produced the telemetry. Note that there are certain "standard -attributes" that have prescribed meanings. +identify what produced the telemetry. Note that there are certain attributes +that have prescribed meanings. A resource is composed of 0 or more [`Entities`](../entities/README.md) and 0 or more attributes not associated with any entity. @@ -35,7 +35,7 @@ The data model below defines a logical model for an Resource (irrespective of th | Field | Type | Description | |------------|----------|-----------------| | Entities | set\ | Defines the set of Entities associated with this resource.

[Entity is defined here](../entities/data-model.md) | -| Attributes | map\ | Additional Attributes that identify the resource.

MUST not change during the lifetime of the resource.

Follows OpenTelemetry [Standard attribute definition](../common/README.md#standard-attribute). | +| Attributes | map\ | Additional Attributes that identify the resource.

MUST not change during the lifetime of the resource.

Follows OpenTelemetry [attribute definition](../common/README.md#attribute). | ## Identity diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index b7cb8cfa976..8a9a08b4cb0 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -13,7 +13,8 @@ For example, a process producing telemetry that is running in a container on Kubernetes has a Pod name, it is in a namespace and possibly is part of a Deployment which also has a name. All three of these attributes can be included in the `Resource`. Note that there are certain -["standard attributes"](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md) that have prescribed meanings. +[attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md) +that have prescribed meanings. The primary purpose of resources as a first-class concept in the SDK is decoupling of discovery of resource information from exporters. This allows for