Merge branch 'main' into patch-1

CHANGELOG.md

@@ -26,6 +26,8 @@ release.
   ([#3884](https://github.com/open-telemetry/opentelemetry-specification/pull/3884))
 - Clarify that logs attributes are a superset of standard attributes.
   ([#3852](https://github.com/open-telemetry/opentelemetry-specification/pull/3852))
+- Add support for empty values.
+  ([#3853](https://github.com/open-telemetry/opentelemetry-specification/pull/3853))
 
 ### Resource
 

spec-compliance-matrix.md

@@ -280,7 +280,7 @@ Note: Support for environment variables is optional.
 |----------------------------------------------------------|-----|------|-----|-------------|------|--------|-----|------|-----|------|-------|
 | OTEL_SDK_DISABLED                                        | -   | +    | -   | -           | -    | -      | +   | -    | -   | -    | -     |
 | OTEL_RESOURCE_ATTRIBUTES                                 | +   | +    | +   | +           | +    | +      | +   | +    | +   | +    | -     |
-| OTEL_SERVICE_NAME                                        | +   | +    | +   | +           | +    | +      | +   |      |     | +    |       |
+| OTEL_SERVICE_NAME                                        | +   | +    | +   | +           | +    | +      | +   |      | +   | +    |       |
 | OTEL_LOG_LEVEL                                           | -   | -    | +   | [-][py1059] | +    | -      | +   |      | -   | -    | -     |
 | OTEL_PROPAGATORS                                         | -   | +    |     | +           | +    | +      | +   | -    | -   | -    | -     |
 | OTEL_BSP_*                                               | +   | +    | +   | +           | +    | +      | +   | +    | -   | +    | -     |

specification/common/README.md

@@ -16,6 +16,7 @@ path_base_for_github_subdir:
 <!-- toc -->
 
 - [Attribute](#attribute)
+  * [Standard Attribute](#standard-attribute)
   * [Attribute Limits](#attribute-limits)
     + [Configurable Parameters](#configurable-parameters)
     + [Exempt Entities](#exempt-entities)
@@ -33,7 +34,7 @@ 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:
+- The attribute value is either[1]:
   - 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.
@@ -65,6 +66,38 @@ See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/b
 See [this document](attribute-type-mapping.md) to find out how to map values obtained
 outside OpenTelemetry into OpenTelemetry attribute values.
 
+**[1]**: NOTE: extending the set of attribute value types is a breaking change.
+This was decided after extensive debate, with arguments as follows:
+
+* Limiting the types of attribute values to a set which has proved sufficient
+  during several years of OpenTelemetry's development is a useful guardrail for
+  design. In taking additional value types off the table, we narrow the solution
+  space and have more productive design conversations.
+* We proposed extending support for complex value types and received significant
+  pushback. Removing the bounds significantly increases the burden on data
+  consumers. Adding additional simple value types doesn't cause the same level
+  of burden, but these can be encoded using existing primitive types. For
+  example, datetime can be encoded as a string or 64 bit integer.
+* Limiting attribute value types to primitives and arrays of primitives supports
+  OpenTelemetry's intent that attributes are metadata, and facilitates the
+  ability for data consumers to create search indexes and perform other
+  statistical analysis.
+
+### Standard Attribute
+
+Attributes are used in various places throughout the OpenTelemetry data model.
+We designate the [previous attribute section](#attribute) as the standard
+attribute definition, in order to facilitate more intuitive and consistent API /
+SDK design.
+
+The standard attribute definition SHOULD be used to represent attributes in data
+modeling unless there is a strong justification to diverge. For example, the Log
+Data Model has an extended [attributes](../logs/data-model.md#field-attributes)
+definition allowing values of [type `Any`](../logs/data-model.md#type-any). This
+reflects that LogRecord attributes are expected to model data produced from
+external log APIs, which do not necessarily have the same value type
+restrictions as the standard attribute definition.
+
 ### Attribute Limits
 
 Execution of erroneous code can result in unintended attributes. If there are no

specification/logs/data-model.md

@@ -112,7 +112,9 @@ Value of type `any` can be one of the following:
 
 - An array (a list) of `any` values,
 
-- A `map<string, any>`.
+- A `map<string, any>`,
+
+- [since 1.31.0] An empty value (e.g. `null`).
 
 #### Type `map<string, any>`
 

specification/overview.md

@@ -22,10 +22,9 @@ weight: 1
   * [Links between spans](#links-between-spans)
 - [Metric Signal](#metric-signal)
   * [Recording raw measurements](#recording-raw-measurements)
-    + [Measure](#measure)
-    + [Measurement](#measurement)
-  * [Recording metrics with predefined aggregation](#recording-metrics-with-predefined-aggregation)
+    + [Instruments](#instruments)
   * [Metrics data model and SDK](#metrics-data-model-and-sdk)
+    + [Views](#views)
 - [Log Signal](#log-signal)
   * [Data model](#data-model)
 - [Baggage Signal](#baggage-signal)
@@ -218,73 +217,61 @@ scenarios.
 
 ## Metric Signal
 
-OpenTelemetry allows to record raw measurements or metrics with predefined
-aggregation and a [set of attributes](./common/README.md#attribute).
+OpenTelemetry allows recording raw measurements or metrics with predefined
+aggregations and a [set of attributes](common/README.md#attribute).
 
-Recording raw measurements using OpenTelemetry API allows to defer to end-user
-the decision on what aggregation algorithm should be applied for this metric as
-well as defining attributes (dimensions). It will be used in client libraries like
-gRPC to record raw measurements "server_latency" or "received_bytes". So end
-user will decide what type of aggregated values should be collected out of these
-raw measurements. It may be simple average or elaborate histogram calculation.
-
-Recording of metrics with the pre-defined aggregation using OpenTelemetry API is
-not less important. It allows to collect values like cpu and memory usage, or
-simple metrics like "queue length".
+Using the OpenTelemetry API to record raw measurements gives end-users the
+flexibility to choose the aggregation algorithm for a given metric. This functionality
+is particularly useful in client libraries such as gRPC, where it enables the
+recording of raw measurements like "server_latency" or "received_bytes." End-users
+then have the autonomy to decide on the aggregation method for these raw measurements,
+options for which range from straightforward averages to more complex histogram calculations.
 
 ### Recording raw measurements
 
-The main classes used to record raw measurements are `Measure` and
-`Measurement`. List of `Measurement`s alongside the additional context can be
-recorded using OpenTelemetry API. So user may define to aggregate those
-`Measurement`s and use the context passed alongside to define additional
-attributes of the resulting metric.
-
-#### Measure
-
-`Measure` describes the type of the individual values recorded by a library. It
-defines a contract between the library exposing the measurements and an
-application that will aggregate those individual measurements into a `Metric`.
-`Measure` is identified by name, description and a unit of values.
-
-#### Measurement
-
-`Measurement` describes a single value to be collected for a `Measure`.
-`Measurement` is an empty interface in API surface. This interface is defined in
-SDK.
+The primary components involved in recording raw measurements using the OpenTelemetry
+API are `Measurement`, `Instrument` and `Meter`. A `Meter` is obtained from a
+`MeterProvider` and used to create an `Instrument`, which is then responsible for capturing
+[measurements](metrics/api.md#measurement).
 
-### Recording metrics with predefined aggregation
-
-The base class for all types of pre-aggregated metrics is called `Metric`. It
-defines basic metric properties like a name and attributes. Classes inheriting from
-the `Metric` define their aggregation type as well as a structure of individual
-measurements or Points. API defines the following types of pre-aggregated
-metrics:
+```
++------------------+
+| MeterProvider    |                 +-----------------+             +--------------+
+|   Meter A        | Measurements... |                 | Metrics...  |              |
+|     Instrument X +-----------------> In-memory state +-------------> MetricReader |
+|     Instrument Y |                 |                 |             |              |
+|   Meter B        |                 +-----------------+             +--------------+
+|     Instrument Z |
+|     ...          |                 +-----------------+             +--------------+
+|     ...          | Measurements... |                 | Metrics...  |              |
+|     ...          +-----------------> In-memory state +-------------> MetricReader |
+|     ...          |                 |                 |             |              |
+|     ...          |                 +-----------------+             +--------------+
++------------------+
+```
 
-- Counter metric to report instantaneous measurement. Counter values can go
-  up or stay the same, but can never go down. Counter values cannot be
-  negative. There are two types of counter metric values - `double` and `long`.
-- Gauge metric to report instantaneous measurement of a numeric value. Gauges can
-  go both up and down. The gauges values can be negative. There are two types of
-  gauge metric values - `double` and `long`.
+#### Instruments
 
-API allows to construct the `Metric` of a chosen type. SDK defines the way to
-query the current value of a `Metric` to be exported.
+[Instruments](metrics/api.md#instrument) are used to report `Measurement`s, and are identified
+by a name, kind, description and a unit of values.
 
-Every type of a `Metric` has it's API to record values to be aggregated. API
-supports both - push and pull model of setting the `Metric` value.
+There are several types of metric instruments for specific use cases, such as counters for
+incrementing values, gauges for capturing current values, and histograms for capturing
+distributions of measurements. Instruments can be synchronous, meaning that they are invoked
+inline by application logic, or asynchronous where the user registers a callback
+function that is invoked on demand by the SDK.
 
 ### Metrics data model and SDK
 
-Metrics data model is [specified here](metrics/data-model.md) and is based on
+The Metrics data model is [specified here](metrics/data-model.md) and is based on
 [metrics.proto](https://github.com/open-telemetry/opentelemetry-proto/blob/master/opentelemetry/proto/metrics/v1/metrics.proto).
 This data model defines three semantics: An Event model used by the API, an
 in-flight data model used by the SDK and OTLP, and a TimeSeries model which
 denotes how exporters should interpret the in-flight model.
 
 Different exporters have different capabilities (e.g. which data types are
 supported) and different constraints (e.g. which characters are allowed in attribute
-keys). Metrics is intended to be a superset of what's possible, not a lowest
+keys). Metrics is intended to be a superset of what's possible, not the lowest
 common denominator that's supported everywhere. All exporters consume data from
 Metrics Data Model via a Metric Producer interface defined in OpenTelemetry SDK.
 
@@ -297,6 +284,13 @@ from the backend.
 See [Metrics Data Model Specification](metrics/data-model.md) for more
 information.
 
+#### Views
+
+[Views](metrics/sdk.md#view) are configurations that specify how the data from an `Instrument` should be processed,
+aggregated, and exported. They can be applied globally through the `MeterProvider` or more
+specifically at the `Meter` level. A `View` allows the customization of metric data beyond the default
+collection behavior, enabling specific aggregations, transformations, and filtering of metrics.
+
 ## Log Signal
 
 ### Data model

specification/trace/api.md

@@ -4,7 +4,7 @@ linkTitle: API
 
 # Tracing API
 
-**Status**: [Stable, Feature-freeze](../document-status.md), except where otherwise specified
+**Status**: [Stable](../document-status.md), except where otherwise specified
 
 <details>
 <summary>Table of Contents</summary>
@@ -543,8 +543,6 @@ Note that [`RecordException`](#record-exception) is a specialized variant of
 
 #### Add Link
 
-**Status**: [Experimental](../document-status.md)
-
 A `Span` MUST have the ability to add `Link`s associated with it after its creation - see [Links](#link).
 `Link`s added after `Span` creation may not be considered by [Samplers](sdk.md#sampler).