From 5ab265dee341471165db6103e2fb7e807c9bea0f Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 10 Jan 2024 14:53:41 -0300 Subject: [PATCH] Remove unwanted files and update links to spec repo --- .../general/attribute-definition.md | 48 ++-- specification/common/attribute-naming.md | 4 - .../common/attribute-requirement-level.md | 4 - .../common/attribute-type-mapping.md | 255 ------------------ specification/common/mapping-to-non-otlp.md | 95 ------- 5 files changed, 28 insertions(+), 378 deletions(-) rename specification/common/README.md => docs/general/attribute-definition.md (70%) delete mode 100644 specification/common/attribute-naming.md delete mode 100644 specification/common/attribute-requirement-level.md delete mode 100644 specification/common/attribute-type-mapping.md delete mode 100644 specification/common/mapping-to-non-otlp.md diff --git a/specification/common/README.md b/docs/general/attribute-definition.md similarity index 70% rename from specification/common/README.md rename to docs/general/attribute-definition.md index 1b46da3e62..42a82a609e 100644 --- a/specification/common/README.md +++ b/docs/general/attribute-definition.md @@ -1,10 +1,9 @@ -# Common specification concepts +# Attribute definition -**Status**: [Stable, Feature-freeze](../document-status.md) +**Status**: [Stable, Feature-freeze][DocumentStatus]
Table of Contents @@ -28,6 +27,7 @@ aliases: [/docs/reference/specification/common/common] 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 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, @@ -53,11 +53,13 @@ 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]`). -See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines. +See [Attribute Naming](attribute-naming.md) for naming guidelines. -See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md) for requirement levels guidelines. +See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines. -See [this document](attribute-type-mapping.md) to find out how to map values obtained +See +[Mapping Arbitrary Data to OTLP AnyValue](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-type-mapping.md) +to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. ### Attribute Limits @@ -115,16 +117,16 @@ 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). +[Metrics Attribute Limits](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#attribute-limits). ## Attribute Collections -[Resources](../resource/sdk.md), Metrics -[data 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 +[Resources](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md), Metrics +[data points](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#metric-points), +[Spans](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-attributes), Span +[Events](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#add-events), Span +[Links](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#link) and +[Log Records](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/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 @@ -134,17 +136,23 @@ 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. +example Span's +[SetAttribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/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 +A typical implementation of +[SetAttribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/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. +[SetAttribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/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. + +[DocumentStatus]: + https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md deleted file mode 100644 index 68f6ca6560..0000000000 --- a/specification/common/attribute-naming.md +++ /dev/null @@ -1,4 +0,0 @@ -# Attribute Naming - -This page has moved to -[github.com/open-telemetry/semantic-conventions/docs/general/attribute-naming.md](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md). diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md deleted file mode 100644 index bcbe62b0a8..0000000000 --- a/specification/common/attribute-requirement-level.md +++ /dev/null @@ -1,4 +0,0 @@ -# Attribute Requirement Levels for Semantic Conventions - -This page has moved to -[github.com/open-telemetry/semantic-conventions/docs/general/attribute-requirement-level.md](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md). diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md deleted file mode 100644 index 532d6156bc..0000000000 --- a/specification/common/attribute-type-mapping.md +++ /dev/null @@ -1,255 +0,0 @@ -# Mapping Arbitrary Data to OTLP AnyValue - -**Status**: [Experimental](../document-status.md) - -
-Table of Contents - - - -- [Converting to AnyValue](#converting-to-anyvalue) - * [Primitive Values](#primitive-values) - + [Integer Values](#integer-values) - + [Enumerations](#enumerations) - + [Floating Point Values](#floating-point-values) - + [String Values](#string-values) - + [Byte Sequences](#byte-sequences) - * [Composite Values](#composite-values) - + [Array Values](#array-values) - + [Associative Arrays With Unique Keys](#associative-arrays-with-unique-keys) - + [Associative Arrays With Non-Unique Keys](#associative-arrays-with-non-unique-keys) - + [Sets](#sets) - * [Other Values](#other-values) - * [Empty Values](#empty-values) - - - -
- -This document defines how to map (convert) arbitrary data (e.g. in-memory -objects) to OTLP's [AnyValue](https://github.com/open-telemetry/opentelemetry-proto/blob/cc4ed55c082cb75e084d40b4ddf3805eda099f97/opentelemetry/proto/common/v1/common.proto#L27). - -The mapping is needed when OpenTelemetry needs to convert a value produced outside -OpenTelemetry into a value that can be exported using an OTLP exporter, or otherwise be -converted to be used inside OpenTelemetry boundaries. Example use cases are the following: - -- In the [Logging SDK](../logs/sdk.md)s, to convert values received - from logging libraries into OpenTelemetry representation. -- In the Collector, to convert values received from various data sources into - [pdata](https://github.com/open-telemetry/opentelemetry-collector/blob/4998703dadd19fa91a88eabf7ccc68d728bee3fd/model/pdata/common.go#L84) - internal representation. - -## Converting to AnyValue - -[AnyValue](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L27) -is capable of representing primitive and structured data of certain types. - -Implementations that have source data in any form, such as in-memory objects -or data coming from other formats that needs to be converted to AnyValue SHOULD -follow the rules described below. - -### Primitive Values - -#### Integer Values - -Integer values which are within the range of 64 bit signed numbers -[-2^63..2^63-1] SHOULD be converted to AnyValue's -[int_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L33) -field. - -Integer values which are outside the range of 64 bit signed numbers SHOULD be -converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field using decimal representation. - -#### Enumerations - -Values, which belong to a limited enumerated set (e.g. a Java -[enum](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html)), SHOULD be -converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field with the value of the string set to the symbolic name of the enumeration. - -If it is not possible to obtain the symbolic name of the enumeration, the -implementation SHOULD map enumeration values to AnyValue's -[int_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L33) -field set to the enum's ordinal value, when such an ordinal number is naturally -obtainable. - -If it is also not possible to obtain the ordinal value, the enumeration SHOULD be -converted to AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -field in any manner that the implementation deems reasonable. - -#### Floating Point Values - -Floating point values which are within the range and precision of IEEE 754 -64-bit floating point numbers (including IEEE 32-bit floating point values) -SHOULD be converted to AnyValue's -[double_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L34) -field. - -Floating point values which are outside the range or precision of IEEE 754 -64-bit floating point numbers (e.g. IEEE 128-bit floating bit values) SHOULD be -converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field using decimal floating point representation. - -#### String Values - -String values which are valid UTF-8 sequences SHOULD be converted to -AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field. - -String values which are not valid Unicode sequences SHOULD be converted to -AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -with the bytes representing the string in the original order and format of the -source string. - -#### Byte Sequences - -Byte sequences (e.g. Go's `[]byte` slice or raw byte content of a file) SHOULD -be converted to AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -field. - -### Composite Values - -#### Array Values - -Values that represent ordered sequences of other values (such as -[arrays](https://docs.oracle.com/javase/specs/jls/se7/html/jls-10.html), -[vectors](https://en.cppreference.com/w/cpp/container/vector), ordered -[lists](https://docs.python.org/3/tutorial/datastructures.html#more-on-lists), -[slices](https://golang.org/ref/spec#Slice_types)) SHOULD be converted to -AnyValue's -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -field. String values and byte sequences are an exception from this rule (see -above). - -The rules described in this document should be applied recursively to each element -of the array. - -#### Associative Arrays With Unique Keys - -Values that represent associative arrays with unique keys (also often known -as maps, dictionaries or key-value stores) SHOULD be converted to AnyValue's -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field. - -If the keys of the source array are not strings, they MUST be converted to -strings by any means available, often via a toString() or stringify functions -available in programming languages. The conversion function MUST be chosen in a -way that ensures that the resulting string keys are unique in the target array. - -The value part of each element of the source array SHOULD be converted to -AnyValue recursively. - -For example a JSON object `{"a": 123, "b": "def"}` SHOULD be converted to - -``` -AnyValue{ - kvlist_value:KeyValueList{ - values:[ - KeyValue{key:"a",value:AnyValue{int_value:123}}, - KeyValue{key:"b",value:AnyValue{string_value:"def"}}, - ] - } -} -``` - -The rules described in this document should be applied recursively to each value -of the associative array. - -#### Associative Arrays With Non-Unique Keys - -Values that represent an associative arrays with non-unique keys where multiple values may be associated with the same key (also sometimes known -as multimaps, multidicts) SHOULD be converted to AnyValue's -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field. - -The resulting -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field MUST list each key only once and the value of each element of -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field MUST be an array represented using AnyValue's -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -field, each element of the -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -representing one value of source array associated with the given key. - -For example an associative array shown in the following table: - -|Key|Value| -|---|---| -|"abc"|123| -|"def"|"foo"| -|"def"|"bar"| - -SHOULD be converted to: - -``` -AnyValue{ - kvlist_value:KeyValueList{ - values:[ - KeyValue{ - key:"abc", - value:AnyValue{array_value:ArrayValue{values[ - AnyValue{int_value:123} - ]}} - }, - KeyValue{ - key:"def", - value:AnyValue{array_value:ArrayValue{values[ - AnyValue{string_value:"foo"}, - AnyValue{string_value:"bar"} - ]}} - }, - ] - } -} -``` - -The rules described in this document should be applied recursively to each value -of the associative array. - -#### Sets - -Unordered collections of unique values (such as -[Java Sets](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Set.html), -[C++ sets](https://en.cppreference.com/w/cpp/container/set), -[Python Sets](https://docs.python.org/3/tutorial/datastructures.html#sets)) SHOULD be -converted to AnyValue's -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -field, where each element of the set becomes an element of the array. - -The rules described in this document should be applied recursively to each value -of the set. - -### Other Values - -Any other values not listed above SHOULD be converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field if the source data can be serialized to a string (can be stringified) -using toString() or stringify functions available in programming languages. - -If the source data cannot be serialized to a string then the value SHOULD be -converted AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -field by serializing it into a byte sequence by any means available. - -If the source data cannot be serialized neither to a string nor to a byte -sequence then it SHOULD by converted to an empty AnyValue. - -### Empty Values - -If the source data has no type associated with it and is empty, null, nil or -otherwise indicates absence of data it SHOULD be converted to an -[empty](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L29) -AnyValue, where all the fields are unset. - -Empty values which has a type associated with them (e.g. empty associative -array) SHOULD be converted using the corresponding rules defined for the types -above. diff --git a/specification/common/mapping-to-non-otlp.md b/specification/common/mapping-to-non-otlp.md deleted file mode 100644 index a82dac3e63..0000000000 --- a/specification/common/mapping-to-non-otlp.md +++ /dev/null @@ -1,95 +0,0 @@ -# OpenTelemetry Transformation to non-OTLP Formats - -**Status**: [Stable](../document-status.md) - -All OpenTelemetry concepts and data recorded using OpenTelemetry API can be -directly and precisely represented using corresponding messages and fields of -OTLP format. However, for other formats this is not always the case. Sometimes a -format will not have a native way to represent a particular OpenTelemetry -concept or a field of a concept. - -This document defines the transformation between OpenTelemetry and formats other -than OTLP, for OpenTelemetry fields and concepts that have no direct semantic -equivalent in those other formats. - -Note: when a format has a direct semantic equivalent for a particular field or -concept then the recommendation in this document MUST be ignored. - -See also additional specific transformation rules for -[Jaeger](../trace/sdk_exporters/jaeger.md) and [Zipkin](../trace/sdk_exporters/zipkin.md). -The specific rules for Jaeger and Zipkin take precedence over the generic rules defined -in this document. - -## Mappings - -### InstrumentationScope - -OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value -pairs associated with the Span, Metric Data Point or LogRecord using the following mapping: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | Recommended | -| `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | Recommended | - - -The following deprecated aliases MUST also be reported with exact same values for -backward compatibility reasons: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `otel.library.name` | string | Deprecated, use the `otel.scope.name` attribute. | `io.opentelemetry.contrib.mongodb` | Recommended | -| `otel.library.version` | string | Deprecated, use the `otel.scope.version` attribute. | `1.0.0` | Recommended | - - -### Span Status - -Span `Status` MUST be reported as key-value pairs associated with the Span, -unless the `Status` is `UNSET`. In the latter case it MUST NOT be reported. - -The following table defines the OpenTelemetry `Status`'s mapping to Span's -key-value pairs: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK` | Recommended | -| `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | Recommended | - -`otel.status_code` MUST be one of the following: - -| Value | Description | -|---|---| -| `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | -| `ERROR` | The operation contains an error. | - - -### Dropped Attributes Count - -OpenTelemetry dropped attributes count MUST be reported as a key-value -pair associated with the corresponding data entity (e.g. Span, Span Link, Span Event, -Metric data point, LogRecord, etc). The key name MUST be `otel.dropped_attributes_count`. - -This key-value pair should only be recorded when it contains a non-zero value. - -### Dropped Events Count - -OpenTelemetry Span's dropped events count MUST be reported as a key-value pair -associated with the Span. The key name MUST be `otel.dropped_events_count`. - -This key-value pair should only be recorded when it contains a non-zero value. - -### Dropped Links Count - -OpenTelemetry Span's dropped links count MUST be reported as a key-value pair -associated with the Span. The key name MUST be `otel.dropped_links_count`. - -This key-value pair should only be recorded when it contains a non-zero value. - -### Instrumentation Scope Attributes - -Exporters to formats that don't have a concept that is equivalent to the Scope -SHOULD record the attributes at the most suitable place in their corresponding format, -typically at the Span, Metric or LogRecord equivalent.