diff --git a/CHANGELOG.md b/CHANGELOG.md index 29e197a522c..14211ce7d9a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,16 +18,29 @@ release. - Define experimental MetricFilter as a mechanism to filter collected metrics by the MetricReader ([#3566](https://github.com/open-telemetry/opentelemetry-specification/pull/3566)) +- Add optional configuration for Prometheus exporters to promote resource attributes to metric attributes + ([#3761](https://github.com/open-telemetry/opentelemetry-specification/pull/3761)) +- Clarifications and flexibility in Exemplar speicification. + ([#3760](https://github.com/open-telemetry/opentelemetry-specification/pull/3760)) ### Logs - Add definition for standard output log record exporter. ([#3741](https://github.com/open-telemetry/opentelemetry-specification/pull/3741)) +- BREAKING: Change `event.name` definition to include `namespace` and removed `event.domain` from log event attributes. + ([#3749](https://github.com/open-telemetry/opentelemetry-specification/pull/3749)) +- BREAKING: Refine the arguments of the emit Event API. Instead of accepting + a `LogRecord`, the individual arguments are enumerated along with the + implementation requirements on how those arguments map to `LogRecord`. + ([#3772](https://github.com/open-telemetry/opentelemetry-specification/pull/3772)) ### Resource ### OpenTelemetry Protocol +- Clarify HTTP endpoint configuration option handling. + ([#3739](https://github.com/open-telemetry/opentelemetry-specification/pull/3739)) + ### Compatibility ### SDK Configuration @@ -46,6 +59,8 @@ release. - Add a new AddLink() operation to Span (experimental). ([#3678](https://github.com/open-telemetry/opentelemetry-specification/pull/3678)) +- Stabilize how exceptions are recorded using the Trace SDK. + ([#3769](https://github.com/open-telemetry/opentelemetry-specification/pull/3769)) ### Metrics @@ -80,6 +95,8 @@ release. - Rename/replace `(client|server).socket.(address|port)` attributes with `network.(peer|local).(address|port)`. ([#3713](https://github.com/open-telemetry/opentelemetry-specification/pull/3713)) +- Add `console` as an exporter type that is supported via environment variable configuration. + ([#3742](https://github.com/open-telemetry/opentelemetry-specification/pull/3742)) ### Supplementary Guidelines diff --git a/specification/common/README.md b/specification/common/README.md index 1f17536bb64..1b46da3e628 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -53,9 +53,9 @@ 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](attribute-naming.md) for naming guidelines. +See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines. -See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines. +See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/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. diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 548703db6f2..68f6ca6560f 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -1,156 +1,4 @@ # Attribute Naming -**Status**: [Stable](../document-status.md) - -
-Table of Contents - - - -- [Name Pluralization guidelines](#name-pluralization-guidelines) -- [Name Reuse Prohibition](#name-reuse-prohibition) -- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) -- [Recommendations for Application Developers](#recommendations-for-application-developers) -- [otel.* Namespace](#otel-namespace) - - - -
- -_This section applies to Resource, Span, Log, and Metric attribute names (also -known as the "attribute keys"). For brevity within this section when we use the -term "name" without an adjective it is implied to mean "attribute name"._ - -Every name MUST be a valid Unicode sequence. - -_Note: we merely require that the names are represented as Unicode sequences. -This specification does not define how exactly the Unicode sequences are -encoded. The encoding can vary from one programming language to another and from -one wire format to another. Use the idiomatic way to represent Unicode in the -particular programming language or wire format._ - -Names SHOULD follow these rules: - -- Use namespacing to avoid name clashes. Delimit the namespaces using a dot - character. For example `service.version` denotes the service version where - `service` is the namespace and `version` is an attribute in that namespace. - -- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside - top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute - inside `telemetry.sdk` namespace. - Note: the fact that an entity is located within another entity is typically - not a sufficient reason for forming nested namespaces. The purpose of a - namespace is to avoid name clashes, not to indicate entity hierarchies. This - purpose should primarily drive the decision about forming nested namespaces. - -- For each multi-word dot-delimited component of the attribute name separate the - words by underscores (i.e. use snake_case). For example `http.response.status_code` - denotes the status code in the http namespace. - -- Names SHOULD NOT coincide with namespaces. For example if - `service.instance.id` is an attribute name then it is no longer valid to have - an attribute named `service.instance` because `service.instance` is already a - namespace. Because of this rule be careful when choosing names: every existing - name prohibits existence of an equally named namespace in the future, and vice - versa: any existing namespace prohibits existence of an equally named - attribute key in the future. - -## Name Pluralization guidelines - -- When an attribute represents a single entity, the attribute name SHOULD be singular. - Examples: `host.name`, `db.user`, `container.id`. - -- When attribute can represent multiple entities, the attribute name SHOULD be pluralized - and the value type SHOULD be an array. E.g. `process.command_args` might include multiple - values: the executable name and command arguments. - -- When an attribute represents a measurement, - [Metric Name Pluralization Guidelines](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#pluralization) - SHOULD be followed for the attribute name. - -## Name Reuse Prohibition - -A new attribute MUST NOT be added with the same name as an attribute that -existed in the past but was renamed (with a corresponding schema file). - -When introducing a new attribute name check all existing schema files to make -sure the name does not appear as a key of any "rename_attributes" section (keys -denote old attribute names in rename operations). - -## Recommendations for OpenTelemetry Authors - -- All names that are part of OpenTelemetry semantic conventions SHOULD be part - of a namespace. - -- When coming up with a new semantic convention make sure to check existing - namespaces ([Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md)) - to see if the new name fits. - -- When a new namespace is necessary consider whether it should be a top-level - namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`). - -- Semantic conventions exist for four areas: for Resource, Span, Log, and Metric - attribute names. In addition, for spans we have two more areas: Event and Link - attribute names. Identical namespaces or names in all these areas MUST have - identical meanings. For example the `http.request.method` span attribute name denotes - exactly the same concept as the `http.request.method` metric attribute, has the same - data type and the same set of possible values (in both cases it records the - value of the HTTP protocol's request method as a string). - -- Semantic conventions MUST limit names to printable Basic Latin characters - (more precisely to - [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) - subset of Unicode code points). It is recommended to further limit names to - the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot - (as namespace delimiter). - -## Recommendations for Application Developers - -As an application developer when you need to record an attribute first consult -existing [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md). -If an appropriate name does not exists you will need to come up with a new name. -To do that consider a few options: - -- The name is specific to your company and may be possibly used outside the - company as well. To avoid clashes with names introduced by other companies (in - a distributed system that uses applications from multiple vendors) it is - recommended to prefix the new name by your company's reverse domain name, e.g. - `com.acme.shopname`. - -- The name is specific to your application that will be used internally only. If - you already have an internal company process that helps you to ensure no name - clashes happen then feel free to follow it. Otherwise it is recommended to - prefix the attribute name by your application name, provided that - the application name is reasonably unique within your organization (e.g. - `myuniquemapapp.longitude` is likely fine). Make sure the application name - does not clash with an existing semantic convention namespace. - -- It is not recommended to use existing OpenTelemetry semantic convention namespace - as a prefix for a new company- or application-specific attribute name. Doing so - may result in a name clash in the future, if OpenTelemetry decides to use that - same name for a different purpose or if some other third party instrumentation - decides to use that exact same attribute name and you combine that instrumentation - with your own. - -- The name may be generally applicable to applications in the industry. In that - case consider submitting a proposal to this specification to add a new name to - the semantic conventions, and if necessary also to add a new namespace. - -It is recommended to limit names to printable Basic Latin characters -(more precisely to -[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) -subset of Unicode code points). - -## otel.* Namespace - -Attribute names that start with `otel.` are reserved to be defined by -OpenTelemetry specification. These are typically used to express OpenTelemetry -concepts in formats that don't have a corresponding concept. - -For example, the `otel.scope.name` attribute is used to record the -instrumentation scope name, which is an OpenTelemetry concept that is natively -represented in OTLP, but does not have an equivalent in other telemetry formats -and protocols. - -Any additions to the `otel.*` namespace MUST be approved as part of -OpenTelemetry specification. +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 index 7f510fe7313..bcbe62b0a84 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -1,76 +1,4 @@ # Attribute Requirement Levels for Semantic Conventions -**Status**: [Stable](../document-status.md) - -
-Table of Contents - - - -- [Required](#required) -- [Conditionally Required](#conditionally-required) -- [Recommended](#recommended) -- [Opt-In](#opt-in) -- [Performance suggestions](#performance-suggestions) - - - -
- -_This section applies to Log, Metric, Resource, and Span, and describes requirement levels for attributes defined in semantic conventions._ - -Attribute requirement levels apply to the [instrumentation library](../glossary.md#instrumentation-library). - -The following attribute requirement levels are specified: - -- [Required](#required) -- [Conditionally Required](#conditionally-required) -- [Recommended](#recommended) -- [Opt-In](#opt-in) - -The requirement level for an attribute is specified by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When specifying requirement levels, a semantic convention MUST take into account signal-specific requirements. - -For example, Metric attributes that may have high cardinality can only be defined with `Opt-In` level. - -A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. - - -For example, [Database semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) references `network.transport` attribute defined in [General attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/README.md) with `Conditionally Required` level on it. - -## Required - -All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.request.method` is an example of a Required attribute. - -_Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._ - -## Conditionally Required - -All instrumentations MUST populate the attribute when the given condition is satisfied. The semantic convention of a `Conditionally Required` attribute MUST clarify the condition under which the attribute is to be populated. - -`http.route` is an example of a conditionally required attribute that is populated when the instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute. - -When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. - - -For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `network.peer.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. - -## Recommended - -Instrumentations SHOULD add the attribute by default if it's readily available and can be [efficiently populated](#performance-suggestions). Instrumentations MAY offer a configuration option to disable Recommended attributes. - -Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD allow for users to -opt-in to emit them as defined for the `Opt-In` requirement level (if the attributes are logically applicable). - -## Opt-In - -Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Opt-In` attributes. - -This attribute requirement level is recommended for attributes that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled explicitly by a user making an informed decision. - -## Performance suggestions - -Here are several examples of expensive operations to be avoided by default: - -- DNS lookups to populate `server.address` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. -- forcing an `http.route` calculation before the HTTP framework calculates it -- reading response stream to find `http.response.body.size` when `Content-Length` header is not available +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/url.md b/specification/common/url.md deleted file mode 100644 index bbe041ba67e..00000000000 --- a/specification/common/url.md +++ /dev/null @@ -1,45 +0,0 @@ -# Semantic conventions for URL - -**Status**: [Experimental](../document-status.md) - -This document defines semantic conventions that describe URL and its components. - -
-Table of Contents - - - -- [Attributes](#attributes) -- [Sensitive information](#sensitive-information) - - - -
- -## Attributes - - -| 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. - - -## 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._ diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index ecb74fc73dd..7f36beddf3c 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -385,11 +385,11 @@ OpenMetrics exemplar unless they would exceed the OpenMetrics In SDK Prometheus (pull) exporters, resource attributes SHOULD be converted to a single [`target_info` metric](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems) -if the resource is not [empty](../resource/sdk.md#the-empty-resource); -otherwise, they MUST be dropped, and MUST NOT be attached as labels to other -metric families. The target_info metric MUST be an info-typed metric whose -labels MUST include the resource attributes, and MUST NOT include any other -labels. There MUST be at most one target_info metric exposed on an SDK +if the resource is not [empty](../resource/sdk.md#the-empty-resource). +The resource attributes MAY be copied to labels of exported metric families +if required by the exporter configuration, or MUST be dropped. The target_info metric MUST be an info-typed +metric whose labels MUST include the resource attributes, and MUST NOT include +any other labels. There MUST be at most one target_info metric exposed on an SDK Prometheus endpoint. In the Collector's Prometheus pull and push (remote-write) exporters, it is diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index 881591044da..ef4794cb046 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -236,17 +236,26 @@ Known values for `OTEL_TRACES_EXPORTER` are: - `"otlp"`: [OTLP](../protocol/otlp.md) - `"zipkin"`: [Zipkin](https://zipkin.io/zipkin-api/) (Defaults to [protobuf](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto) format) +- `"console"`: [Standard Output](../trace/sdk_exporters/stdout.md) +- `"logging"`: [Standard Output](../trace/sdk_exporters/stdout.md). It is a deprecated value left for backwards compatibility. It SHOULD +NOT be supported by new implementations. - `"none"`: No automatically configured exporter for traces. Known values for `OTEL_METRICS_EXPORTER` are: - `"otlp"`: [OTLP](../protocol/otlp.md) - `"prometheus"`: [Prometheus](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md) +- `"console"`: [Standard Output](../metrics/sdk_exporters/stdout.md) +- `"logging"`: [Standard Output](../metrics/sdk_exporters/stdout.md). It is a deprecated value left for backwards compatibility. It SHOULD +NOT be supported by new implementations. - `"none"`: No automatically configured exporter for metrics. Known values for `OTEL_LOGS_EXPORTER` are: - `"otlp"`: [OTLP](../protocol/otlp.md) +- `"console"`: [Standard Output](../logs/sdk_exporters/stdout.md) +- `"logging"`: [Standard Output](../logs/sdk_exporters/stdout.md). It is a deprecated value left for backwards compatibility. It SHOULD +NOT be supported by new implementations. - `"none"`: No automatically configured exporter for logs. ## Metrics SDK Configuration diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 6c59ac226b3..b377c704e20 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -14,6 +14,7 @@ * [EventLogger Operations](#eventlogger-operations) + [Create EventLogger](#create-eventlogger) + [Emit Event](#emit-event) +- [Optional and required parameters](#optional-and-required-parameters) @@ -30,11 +31,11 @@ From OpenTelemetry's perspective LogRecords and Events are both represented using the same [data model](./data-model.md). However, OpenTelemetry does recognize a subtle semantic difference between -LogRecords and Events: Events are LogRecords which have a `name` and `domain`. -Within a particular `domain`, the `name` uniquely defines a particular class or -type of event. Events with the same `domain` / `name` follow the same schema -which assists in analysis in observability platforms. Events are described in -more detail in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). +LogRecords and Events: Events are LogRecords which have a `name` which uniquely +defines a particular class or type of event. All events with the same `name` +have `Payloads` that conform to the same schema, which assists in analysis in +observability platforms. Events are described in more detail in +the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). While the logging space has a diverse legacy with many existing logging libraries in different languages, there is not ubiquitous alignment with @@ -65,8 +66,6 @@ on `EventLogger`. * `logger` - the delegate [Logger](./bridge-api.md#logger) used to emit `Events` as `LogRecord`s. -* `event_domain` - the domain of emitted events, used to set the `event.domain` - attribute. #### Emit Event @@ -76,19 +75,55 @@ This function MAY be named `logEvent`. **Parameters:** -* `event_name` - the Event name. This argument MUST be recorded as a `LogRecord` - attribute with the key `event.name`. Care MUST be taken by the implementation - to not override or delete this attribute while the Event is emitted to - preserve its identity. -* `logRecord` - the [LogRecord](./data-model.md#log-and-event-record-definition) representing the Event. +* The `Name` of the Event, as described + in [event.name semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). +* The (`AnyValue`) (optional) `Payload` of the Event. +* The `Timestamp` (optional) of the Event. +* The [Context](../context/README.md) (optional) associated with the Event. +* The `SeverityNumber` (optional) of the Event. +* The `Attributes` (optional) of the Event. Event `Attributes` provide + additional details about the Event which are not part of the + well-defined `Payload`. **Implementation Requirements:** -The implementation MUST [emit](./bridge-api.md#emit-a-logrecord) the `logRecord` to -the `logger` specified when [creating the EventLogger](#create-eventlogger) -after making the following changes: - -* The `event_domain` specified - when [creating the EventLogger](#create-eventlogger) MUST be set as - the `event.domain` attribute on the `logRecord`. -* The `event_name` MUST be set as the `event.name` attribute on the `logRecord`. +The implementation MUST use the parameters +to [emit a logRecord](./bridge-api.md#emit-a-logrecord) using the `logger` +specified when [creating the EventLogger](#create-eventlogger) as follows: + +* The `Name` MUST be used to set + the `event.name` [Attribute](./data-model.md#field-attributes). If + the `Attributes` provided by the user contain an `event.name` attribute the + value provided in the `Name` takes precedence. +* If provided by the user, the `Payload` MUST be used to set + the [Body](./data-model.md#field-body). If not provided, `Body` MUST not be + set. +* If provided by the user, the `Timestamp` MUST be used to set + the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` + MUST be set to the current time when [emit](#emit-event) was called. +* The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST not be + set. (NOTE: [emit a logRecord](./bridge-api.md#emit-a-logrecord) will + set `ObservedTimestamp` to the current time when unset.) +* If provided by the user, the `Context` MUST be used to set + the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context` + MUST be set to the current Context. +* If provided by the user, the `SeverityNumber` MUST be used to set + the [Severity Number](./data-model.md#field-severitynumber) when emitting the + logRecord. If not provided, `SeverityNumber` MUST be set + to `SEVERITY_NUMBER_INFO=9`. +* The [Severity Text](./data-model.md#field-severitytext) MUST not be set. +* If provided by the user, the `Attributes` MUST be used to set + the [Attributes](./data-model.md#field-attributes). The user + provided `Attributes` MUST not take over the `event.name` + attribute previously discussed. + +## Optional and required parameters + +The operations defined include various parameters, some of which are marked +optional. Parameters not marked optional are required. + +For each optional parameter, the API MUST be structured to accept it, but MUST +NOT obligate a user to provide it. + +For each required parameter, the API MUST be structured to obligate a user to +provide it. diff --git a/specification/metrics/README.md b/specification/metrics/README.md index 82b94af96d8..8fad95d83a7 100644 --- a/specification/metrics/README.md +++ b/specification/metrics/README.md @@ -30,7 +30,7 @@ Given there are many well-established metrics solutions that exist today, it is important to understand the goals of OpenTelemetry’s metrics effort: * **Being able to connect metrics to other signals**. For example, metrics and - traces can be correlated via exemplars, and metrics attributes can be enriched + traces can be correlated via [exemplars](data-model.md#exemplars), and metrics attributes can be enriched via [Baggage](../baggage/api.md) and [Context](../context/README.md). Additionally, [Resource](../resource/sdk.md) can be applied to [logs](../overview.md#log-signal)/[metrics](../overview.md#metric-signal)/[traces](../overview.md#tracing-signal) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f859cab9252..47fc44fda3b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -54,6 +54,7 @@ linkTitle: SDK + [AlwaysOn](#alwayson) + [AlwaysOff](#alwaysoff) + [TraceBased](#tracebased) + + [Configuration](#configuration-2) * [ExemplarReservoir](#exemplarreservoir) * [Exemplar defaults](#exemplar-defaults) + [SimpleFixedSizeExemplarReservoir](#simplefixedsizeexemplarreservoir) @@ -976,11 +977,21 @@ Using this ExemplarFilter is as good as disabling Exemplar feature. An ExemplarFilter which makes those measurements eligible for being an Exemplar, which are recorded in the context of a sampled parent span. +#### Configuration + +The ExemplarFilter SHOULD be a configuration parameter of a `MeterProvider` for +an SDK. The default value SHOULD be `TraceBased`. The filter configuration +SHOULD follow the [environment variable specification](../configuration/sdk-environment-variables.md#exemplar). + ### ExemplarReservoir The `ExemplarReservoir` interface MUST provide a method to offer measurements to the reservoir and another to collect accumulated Exemplars. +A new `ExemplarReservoir` MUST be created for every known timeseries data point, +as determined by aggregation and view configuration. This data point, and its +set of defining attributes, are referred to as the associated timeseries point. + The "offer" method SHOULD accept measurements, including: - The `value` of the measurement. @@ -997,18 +1008,26 @@ span context and baggage can be inspected at this point. The "offer" method does not need to store all measurements it is given and MAY further sample beyond the `ExemplarFilter`. +The "offer" method MAY accept a filtered subset of `Attributes` which diverge +from the timeseries the reservoir is associated with. This MUST be clearly +documented in the API interface and the reservoir MUST be given the `Attributes` +associated with its timeseries point either at construction so that additional +sampling performed by the reservoir has access to all attributes from a +measurement in the "offer" method. SDK authors are encouraged to benchmark +whether this option works best for their implementation. + The "collect" method MUST return accumulated `Exemplar`s. Exemplars are expected to abide by the `AggregationTemporality` of any metric point they are recorded with. In other words, Exemplars reported against a metric data point SHOULD have -occurred within the start/stop timestamps of that point. SDKs are free to +occurred within the start/stop timestamps of that point. SDKs are free to decide whether "collect" should also reset internal storage for delta temporal aggregation collection, or use a more optimal implementation. `Exemplar`s MUST retain any attributes available in the measurement that -are not preserved by aggregation or view configuration. Specifically, at a -minimum, joining together attributes on an `Exemplar` with those available -on its associated metric data point should result in the full set of attributes -from the original sample measurement. +are not preserved by aggregation or view configuration for the associated +timeseries. Joining together attributes on an `Exemplar` with +those available on its associated metric data point should result in the +full set of attributes from the original sample measurement. The `ExemplarReservoir` SHOULD avoid allocations when sampling exemplars. @@ -1019,9 +1038,15 @@ The SDK SHOULD include two types of built-in exemplar reservoirs: 1. `SimpleFixedSizeExemplarReservoir` 2. `AlignedHistogramBucketExemplarReservoir` -By default, explicit bucket histogram aggregation with more than 1 bucket will -use `AlignedHistogramBucketExemplarReservoir`. All other aggregations will use -`SimpleFixedSizeExemplarReservoir`. +By default: + +- Explicit bucket histogram aggregation with more than 1 bucket will +use `AlignedHistogramBucketExemplarReservoir`. +- Base2 Exponential Histogram Aggregation SHOULD use a + `SimpleFixedSizeExemplarReservoir` with a reservoir equal to the + smaller of the maximum number of buckets configured on the aggregation or + twenty (e.g. `min(20, max_buckets)`). +- All other aggregations will use `SimpleFixedSizeExemplarReservoir`. #### SimpleFixedSizeExemplarReservoir @@ -1031,7 +1056,11 @@ measurements should be sampled. For example, the [simple reservoir sampling algorithm](https://en.wikipedia.org/wiki/Reservoir_sampling) can be used: ``` - bucket = random_integer(0, num_measurements_seen) + if num_measurements_seen < num_buckets then + bucket = num_measurements_seen + else + bucket = random_integer(0, num_measurements_seen) + end if bucket < num_buckets then reservoir[bucket] = measurement end @@ -1042,8 +1071,9 @@ cycle. For the above example, that would mean that the `num_measurements_seen` count is reset every time the reservoir is collected. This Exemplar reservoir MAY take a configuration parameter for the size of the -reservoir pool. If no size configuration is provided, the default size of `1` -SHOULD be used. +reservoir. If no size configuration is provided, the default size MAY be +the number of possible concurrent threads (e.g. numer of CPUs) to help reduce +contention. Otherwise, a default size of `1` SHOULD be used. #### AlignedHistogramBucketExemplarReservoir diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 8470a55694d..f72062e7c7a 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -25,3 +25,9 @@ A Prometheus Exporter MAY support [OpenMetrics Text Format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#openmetrics-text-format), including the [Exemplars](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars). + +A Prometheus Exporter MAY offer configuration to add resource attributes as metric attributes. +By default, it MUST NOT add any resource attributes as metric attributes. +The configuration SHOULD allow the user to select which resource attributes to copy (e.g. +include / exclude or regular expression based). Copied Resource attributes MUST NOT be +excluded from target_info. diff --git a/specification/protocol/exporter.md b/specification/protocol/exporter.md index 32c8bc5c69e..22cf934c613 100644 --- a/specification/protocol/exporter.md +++ b/specification/protocol/exporter.md @@ -13,11 +13,21 @@ This document specifies the configuration options available to the OpenTelemetry The following configuration options MUST be available to configure the OTLP exporter. Each configuration option MUST be overridable by a signal specific option. -- **Endpoint (OTLP/HTTP)**: Target URL to which the exporter is going to send spans, metrics, or logs. The endpoint MUST be a valid URL with scheme (http or https) and host, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). A scheme of https indicates a secure connection. When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as [described below](#endpoint-urls-for-otlphttp). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details. +- **Endpoint (OTLP/HTTP)**: Target URL to which the exporter is going to send spans, metrics, or logs. + The implementation MUST honor the following [URL components](https://datatracker.ietf.org/doc/html/rfc3986#section-3): + - scheme (`http` or `https`) + - host + - port + - path + + The implementation MAY ignore all other URL components. + + A scheme of `https` indicates a secure connection. + When using `OTEL_EXPORTER_OTLP_ENDPOINT`, exporters MUST construct per-signal URLs as [described below](#endpoint-urls-for-otlphttp). The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications). See the [OTLP Specification][otlphttp-req] for more details. - Default: `http://localhost:4318` [1] - Env vars: `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` -- **Endpoint (OTLP/gRPC)**: Target to which the exporter is going to send spans, metrics, or logs. The endpoint SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the endpoint MUST accept a URL with a scheme of either `http` or `https`. A scheme of `https` indicates a secure connection and takes precedence over the `insecure` configuration setting. A scheme of `http` indicates an insecure connection and takes precedence over the `insecure` configuration setting. If the gRPC client implementation does not support an endpoint with a scheme of `http` or `https` then the endpoint SHOULD be transformed to the most sensible format for that implementation. +- **Endpoint (OTLP/gRPC)**: Target to which the exporter is going to send spans, metrics, or logs. The option SHOULD accept any form allowed by the underlying gRPC client implementation. Additionally, the option MUST accept a URL with a scheme of either `http` or `https`. A scheme of `https` indicates a secure connection and takes precedence over the `insecure` configuration setting. A scheme of `http` indicates an insecure connection and takes precedence over the `insecure` configuration setting. If the gRPC client implementation does not support an endpoint with a scheme of `http` or `https` then the endpoint SHOULD be transformed to the most sensible format for that implementation. - Default: `http://localhost:4317` [1] - Env vars: `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` diff --git a/specification/trace/exceptions.md b/specification/trace/exceptions.md index 303f3b04234..8ede02b5886 100644 --- a/specification/trace/exceptions.md +++ b/specification/trace/exceptions.md @@ -1,6 +1,6 @@ # Exceptions -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md) This document defines how to record exceptions and their required attributes. diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 33d7a2aafa9..b2632067aad 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -212,7 +212,6 @@ Semantic Conventions defines the set of fields in the OTLP data model: - For log records that are [Log Events](logs/event-api.md) - The following data provided to [emit event](logs/event-api.md#emit-event): - The event name (the value of the `event.name` attribute) - - The event domain (the value of the `event.domain` attribute) Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: