open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove files to keep

This commit is contained in:
Jack Berg 2023-11-07 14:01:24 -06:00 committed by Josh Suereth
parent 04d784279e
commit 7e251196c9
4 changed files with 0 additions and 545 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
specification/common/README.md
View File

@ -1,150 +0,0 @@
<!--- Hugo front matter used to generate the website version of this page:
aliases: [/docs/reference/specification/common/common]
--->
# Common specification concepts
**Status**: [Stable, Feature-freeze](../document-status.md)
<details>
<summary>Table of Contents</summary>
<!-- toc -->
- [Attribute](#attribute)
* [Attribute Limits](#attribute-limits)
+ [Configurable Parameters](#configurable-parameters)
+ [Exempt Entities](#exempt-entities)
- [Attribute Collections](#attribute-collections)
<!-- tocstop -->
</details>
## Attribute
<a id="attributes"></a>
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.
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]`).
See [Attribute Naming](attribute-naming.md) for naming 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
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](#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.
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` or `LogRecordAttributeCountLimit`. 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;
#### 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](../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
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.

255
specification/common/attribute-type-mapping.md
View File

@ -1,255 +0,0 @@
# Mapping Arbitrary Data to OTLP AnyValue
**Status**: [Experimental](../document-status.md)
<details>
<summary>Table of Contents</summary>
<!-- toc -->
- [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)
<!-- tocstop -->
</details>
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.

95
specification/common/mapping-to-non-otlp.md
View File

@ -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:
<!-- semconv otel.scope -->
| 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 |
<!-- endsemconv -->
The following deprecated aliases MUST also be reported with exact same values for
backward compatibility reasons:
<!-- semconv otel.library -->
| 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 |
<!-- endsemconv -->
### 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:
<!-- semconv otel_span -->
| 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. |
<!-- endsemconv -->
### 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.

45
specification/common/url.md
View File

@ -1,45 +0,0 @@
# Semantic conventions for URL
**Status**: [Experimental](../document-status.md)
This document defines semantic conventions that describe URL and its components.
<details>
<summary>Table of Contents</summary>
<!-- toc -->
- [Attributes](#attributes)
- [Sensitive information](#sensitive-information)
<!-- tocstop -->
</details>
## Attributes
<!-- semconv url -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended |
| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended |
| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended |
| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended |
| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended |
**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless.
`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`.
`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes.
**[2]:** When missing, the value is assumed to be `/`
**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it.
<!-- endsemconv -->
## Sensitive information
Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) subcomponent, MUST NOT be recorded.
Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing `url.query` attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties.
_Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._