Skip to content

Latest commit

 

History

History
176 lines (138 loc) · 8.42 KB

README.md

File metadata and controls

176 lines (138 loc) · 8.42 KB
Raw

Common specification concepts

Status: Stable, Feature-freeze

Table of Contents

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.
  • 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.
    • 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 [].

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.

Attribute values of null are not valid and attempting to set a null value is undefined behavior.

null values SHOULD NOT be allowed in arrays. 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 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 indices that are kept in sync (e.g., two attributes header_keys and header_values, 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 for naming guidelines.

See Requirement Level for requirement levels guidelines.

See this document to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values.

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.

By default an SDK SHOULD apply truncation as per the list of configurable parameters below.

If an SDK provides a way to:

  • set an attribute value length limit such that for each attribute value:
    • 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,
    • 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 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 emitted more than once per record on which an attribute is set.

If the SDK implements the limits above, it MUST provide a way to change these limits programmatically. Names of the configuration options SHOULD be the same as in the list below.

An SDK MAY implement model-specific limits, for example SpanAttributeCountLimit. If both a general and a model-specific limit are implemented, then the SDK MUST first attempt to 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

  • 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

Resource attributes SHOULD be exempt from the limits described above as resources are not susceptible to the scenarios (auto-instrumentation) that result in excessive attributes count or size. Resources are also sent only once per batch instead of per span so it is relatively cheaper to have more/larger attributes on them. Resources are also immutable by design and they are generally passed down to TracerProvider along with limits. This makes it awkward to implement 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.

Attribute Collections

Resources, Metrics data points, Spans, Span Events, Span Links and Log Records 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 API.

A typical implementation of SetAttribute 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 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.

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.