From c861b8eb6b0372f22b835f46d2cc922645965b43 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Tue, 4 Jun 2024 15:45:12 -0400 Subject: [PATCH] Rename Experimental to Development according to OTEP 0232 (#4061) Resolves https://github.com/open-telemetry/opentelemetry-specification/issues/4051 [OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md) brought new stability definitions. The impact on this repository is that we need to rename "Experimental" to "Development". All other existing statuses remain unchanged. Note: OTEP 0232 also introduces other levels, such as Alpha, Beta, etc. We will need to decide separately if we want to start using these levels in this repository. --- .github/CODEOWNERS | 6 +-- development/README.md | 20 +++++++++ .../metrics/config-service.md | 2 +- {experimental => development}/trace/zpages.md | 0 experimental/README.md | 15 ------- spec-compliance-matrix.md | 2 +- .../common/attribute-type-mapping.md | 2 +- .../compatibility/logging_trace_context.md | 2 +- specification/compatibility/opentracing.md | 2 +- .../prometheus_and_openmetrics.md | 2 +- .../configuration/file-configuration.md | 2 +- .../sdk-environment-variables.md | 6 +-- specification/document-status.md | 8 +++- specification/logs/event-api.md | 2 +- specification/logs/event-sdk.md | 2 +- specification/logs/sdk.md | 10 ++--- specification/metrics/api.md | 4 +- specification/metrics/data-model.md | 6 +-- specification/metrics/sdk.md | 26 ++++++------ .../metrics/sdk_exporters/prometheus.md | 2 +- specification/protocol/file-exporter.md | 2 +- specification/schemas/file_format_v1.0.0.md | 2 +- specification/schemas/file_format_v1.1.0.md | 2 +- specification/semantic-conventions.md | 4 +- specification/telemetry-stability.md | 2 +- specification/trace/sdk.md | 10 ++--- specification/trace/tracestate-handling.md | 2 +- .../trace/tracestate-probability-sampling.md | 2 +- specification/versioning-and-stability.md | 42 ++++++++++--------- 29 files changed, 101 insertions(+), 88 deletions(-) create mode 100644 development/README.md rename {experimental => development}/metrics/config-service.md (99%) rename {experimental => development}/trace/zpages.md (100%) delete mode 100644 experimental/README.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a03601d88a4..fdf64f6758a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -16,15 +16,15 @@ * @open-telemetry/technical-committee @open-telemetry/specs-approvers # Trace owners (global + trace) -experimental/trace/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers +development/trace/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers specification/trace/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-trace-approvers # Metrics owners (global + metrics) -experimental/metrics/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers +development/metrics/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers specification/metrics/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-metrics-approvers # Logs owners (global + logs) -experimental/logs/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers +development/logs/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers specification/logs/ @open-telemetry/technical-committee @open-telemetry/specs-approvers @open-telemetry/specs-logs-approvers # Semantic Conventions owners (global) diff --git a/development/README.md b/development/README.md new file mode 100644 index 00000000000..f1e3590563f --- /dev/null +++ b/development/README.md @@ -0,0 +1,20 @@ +# Features in Development + +This folder is used for features in +[Development](../specification/document-status.md). `Development` status is for components +that are on track to become part of the specification, but that require a faster cadence +of merges and collaboration. + +Features in Development must be: + +- Implementable as a plugin to OpenTelemetry components (API, SDK, collector, etc.). +- Be in active development or testing. +- Approved as a general direction via OTEP process. + +To avoid any confusion, all files in this directory must have a note about its Development status. + +Development status precedes the alpha version (see +[OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#explanation)). +All changes in the `development` folder go through the regular review process. Changes are allowed to be merged faster as completeness of a solution is not a requirement. Approval means that proposed changes are OK for experimentation. + +When the feature or parts of it are developed far enough to declare them as an alpha version of a main project and move out of the Development status, it must go through a **new** OTEP PR and it must be expected that design and APIs will be changed. In fact, the same people who approved the experiment may likely be the most critical reviewers. It demonstrates an interest and involvement, not critique. diff --git a/experimental/metrics/config-service.md b/development/metrics/config-service.md similarity index 99% rename from experimental/metrics/config-service.md rename to development/metrics/config-service.md index 03ab0b7e5a7..11884815943 100644 --- a/experimental/metrics/config-service.md +++ b/development/metrics/config-service.md @@ -122,7 +122,7 @@ metrics on a push-based model. ## Implementation Details -Because this specification is experimental, and may imply substantial changes to +Because this specification is in Development, and may imply substantial changes to the existing system, we provide additional details on the example prototype implementations available on the [contrib collector](https://github.com/vmingchen/opentelemetry-collector-contrib) and diff --git a/experimental/trace/zpages.md b/development/trace/zpages.md similarity index 100% rename from experimental/trace/zpages.md rename to development/trace/zpages.md diff --git a/experimental/README.md b/experimental/README.md deleted file mode 100644 index 466bbf4d943..00000000000 --- a/experimental/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Experimental features - -This folder will be used to develop experimental features. Experimental status allows to develop components that are on trajectory to become a part of a main project while allowing a faster cadence of merges and collaboration. - -Experimental features must be: - -- Implementable as a plugin to OpenTelemetry components (API, SDK, collector, etc.). -- Be in active development or testing. -- Approved as a general direction via OTEP process. - -All files in experimental folder must have a note about it's experimental status to avoid any confusion. - -Experimental status precedes the alpha version. All changes in the experimental folder go through the regular review process. Changes are allowed to be merged faster as completeness of a solution is not a requirement. Approval means that proposed changes are OK for experimentation. - -When the feature or parts of it are developed far enough to declare them as an alpha version of a main project and move out of the experimental status, it must go through a **new** OTEP PR and it must be expected that design and APIs will be changed. In fact, the same people who approved the experiment may likely be the most critical reviewers. It demonstrates an interest and involvement, not critique. diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 9badcf77d6f..a7c8b203604 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -204,7 +204,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t ## Events Features for the [Events API](specification/logs/event-api.md) and the [Events SDK](specification/logs/event-sdk.md). -Disclaimer: Events are currently an experimental work in progress. +Disclaimer: Events are currently in Development status - work in progress. | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | |----------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------| diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md index 1e546021785..851d386158c 100644 --- a/specification/common/attribute-type-mapping.md +++ b/specification/common/attribute-type-mapping.md @@ -4,7 +4,7 @@ linkTitle: Mapping to AnyValue # Mapping Arbitrary Data to OTLP AnyValue -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md)
Table of Contents diff --git a/specification/compatibility/logging_trace_context.md b/specification/compatibility/logging_trace_context.md index c2c0349587b..5c7f5e9190e 100644 --- a/specification/compatibility/logging_trace_context.md +++ b/specification/compatibility/logging_trace_context.md @@ -1,6 +1,6 @@ # Trace Context in non-OTLP Log Formats -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md)
Table of Contents diff --git a/specification/compatibility/opentracing.md b/specification/compatibility/opentracing.md index b76a5363cba..d2b81a5d03d 100644 --- a/specification/compatibility/opentracing.md +++ b/specification/compatibility/opentracing.md @@ -574,7 +574,7 @@ startSpan(name: string, options: SpanOptions = {}): Span { Using both the OpenTracing Shim and the OpenTelemetry API in the same codebase may result in traces using the incorrect parent `Span`, given the different implicit/explicit propagation expectations. For this case, the Shim MAY offer -**experimental** integration with the OpenTelemetry implicit in-process +**in-Development** integration with the OpenTelemetry implicit in-process propagation via an **explicit** setting, warning the user incorrect parent values may be consumed: diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 9ed1439d829..135147b09d6 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -7,7 +7,7 @@ aliases: # Prometheus and OpenMetrics Compatibility -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md)
Table of Contents diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index f05753aad75..e8a01dbc56a 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -4,7 +4,7 @@ linkTitle: File # File Configuration -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) diff --git a/specification/configuration/sdk-environment-variables.md b/specification/configuration/sdk-environment-variables.md index 30c3392c551..50923b015f5 100644 --- a/specification/configuration/sdk-environment-variables.md +++ b/specification/configuration/sdk-environment-variables.md @@ -225,7 +225,7 @@ _is no specified default, or configuration via environment variables_. ## Prometheus Exporter -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) | Name | Description | Default | | ----------------------------- | --------------------------------| ---------------------------- | @@ -274,7 +274,7 @@ NOT be supported by new implementations. ### Exemplar -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) | Name | Description | Default | Notes | |-----------------|---------|-------------|---------| @@ -298,7 +298,7 @@ that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting- ## File Configuration -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) Environment variables involved in [file configuration](file-configuration.md). diff --git a/specification/document-status.md b/specification/document-status.md index f8fb54af196..cc0400adc04 100644 --- a/specification/document-status.md +++ b/specification/document-status.md @@ -11,11 +11,15 @@ The support guarantees and allowed changes are governed by the lifecycle of the |Status |Explanation| |--------------------|-----------| -|No explicit "Status"|Equivalent to Experimental.| -|Experimental |Breaking changes are allowed.| +|No explicit "Status"|Equivalent to Development.| +|Development |Breaking changes are allowed.| |Stable |Breaking changes are no longer allowed. See [stability guarantees](versioning-and-stability.md#stable) for details.| |Deprecated |Changes are no longer allowed, except for editorial changes.| +The specification follows +[OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#explanation) +maturity level definitions. + ## Feature freeze In addition to the statuses above, documents may be marked as `Feature-freeze`. These documents are not currently accepting new feature requests, to allow the Technical Committee time to focus on other areas of the specification. Editorial changes are still accepted. Changes that address production issues with existing features are still accepted. diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 0602db47503..5180a21ca3b 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -1,6 +1,6 @@ # Events API -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md)
Table of Contents diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 1ebb3ba3dd3..a4b317d29cd 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -1,6 +1,6 @@ # Events SDK -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md)
Table of Contents diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 5efb354db75..99372428d57 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -71,7 +71,7 @@ working `Logger` MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. -**Status**: [Experimental](../document-status.md) - The `LoggerProvider` MUST +**Status**: [Development](../document-status.md) - The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) using the configured [LoggerConfigurator](#loggerconfigurator), and create a `Logger` whose behavior conforms to that `LoggerConfig`. @@ -79,7 +79,7 @@ a `Logger` whose behavior conforms to that `LoggerConfig`. ### Configuration Configuration ( -i.e. [LogRecordProcessors](#logrecordprocessor) and (**experimental**) [LoggerConfigurator](#loggerconfigurator)) +i.e. [LogRecordProcessors](#logrecordprocessor) and (**Development**) [LoggerConfigurator](#loggerconfigurator)) MUST be owned by the `LoggerProvider`. The configuration MAY be applied at the time of `LoggerProvider` creation if appropriate. @@ -93,7 +93,7 @@ configuration only via this reference. #### LoggerConfigurator -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A `LoggerConfigurator` is a function which computes the [LoggerConfig](#loggerconfig) for a [Logger](#logger). @@ -163,7 +163,7 @@ registered [LogRecordProcessors](#logrecordprocessor). ## Logger -**Status**: [Experimental](../document-status.md) - `Logger` MUST behave +**Status**: [Development](../document-status.md) - `Logger` MUST behave according to the [LoggerConfig](#loggerconfig) computed during [logger creation](#logger-creation). If the `LoggerProvider` supports updating the [LoggerConfigurator](#loggerconfigurator), then upon update @@ -171,7 +171,7 @@ the `Logger` MUST be updated to behave according to the new `LoggerConfig`. ### LoggerConfig -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A `LoggerConfig` defines various configurable aspects of a `Logger`'s behavior. It consists of the following parameters: diff --git a/specification/metrics/api.md b/specification/metrics/api.md index a0430082014..6e79ad15f11 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -190,7 +190,7 @@ will have the following parameters: one of the other kinds, whether it is synchronous or asynchronous * An optional `unit` of measure * An optional `description` -* Optional `advisory` parameters (**experimental**) +* Optional `advisory` parameters (**development**) Instruments are associated with the Meter during creation. Instruments are identified by the `name`, `kind`, `unit`, and `description`. @@ -274,7 +274,7 @@ boundaries to use if aggregating to ##### Instrument advisory parameter: `Attributes` -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) Applies to all instrument types. diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md index f6a283c2e28..e5123622802 100644 --- a/specification/metrics/data-model.md +++ b/specification/metrics/data-model.md @@ -1087,7 +1087,7 @@ of cardinality outside of the process. ## Resets and Gaps -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) When the `StartTimeUnixNano` field is present, it allows the consumer to observe when there are gaps and overlapping writers in a stream. @@ -1161,7 +1161,7 @@ of reaggregation for cumulative series. ## Overlap -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) Overlap occurs when more than one metric data point is defined for a metric stream within a time window. Overlap is usually caused through @@ -1200,7 +1200,7 @@ gaps to zero width in these cases, without any overlap. ## Stream Manipulations -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) Pending introduction. diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2b9747fa97f..d91d2758054 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -132,7 +132,7 @@ When a Schema URL is passed as an argument when creating a `Meter` the emitted telemetry for that `Meter` MUST be associated with the Schema URL, provided that the emitted data format is capable of representing such association. -**Status**: [Experimental](../document-status.md) - The `MeterProvider` MUST +**Status**: [Development](../document-status.md) - The `MeterProvider` MUST compute the relevant [MeterConfig](#meterconfig) using the configured [MeterConfigurator](#meterconfigurator), and create a `Meter` whose behavior conforms to that `MeterConfig`. @@ -141,7 +141,7 @@ a `Meter` whose behavior conforms to that `MeterConfig`. Configuration ( i.e. [MetricExporters](#metricexporter), [MetricReaders](#metricreader), [Views](#view), -and (**experimental**) [MeterConfigurator](#meterconfigurator)) MUST be +and (**Development**) [MeterConfigurator](#meterconfigurator)) MUST be owned by the `MeterProvider`. The configuration MAY be applied at the time of `MeterProvider` creation if appropriate. @@ -155,7 +155,7 @@ configuration only via this reference. #### MeterConfigurator -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A `MeterConfigurator` is a function which computes the [MeterConfig](#meterconfig) for a [Meter](#meter). @@ -396,7 +396,7 @@ The SDK MUST accept the following stream configuration parameters: If the user does not provide an `exemplar_reservoir` value, the `MeterProvider` MUST apply a [default exemplar reservoir](#exemplar-defaults). -* **Status**: [Experimental](../document-status.md) - +* **Status**: [Development](../document-status.md) - `aggregation_cardinality_limit`: A positive integer value defining the maximum number of data points allowed to be emitted in a collection cycle by a single instrument. See [cardinality limits](#cardinality-limits), below. @@ -771,7 +771,7 @@ of metrics across successive collections. ### Cardinality limits -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) SDKs SHOULD support being configured with a cardinality limit. The number of unique combinations of attributes is called cardinality. For a given metric, the @@ -837,7 +837,7 @@ temporality. Distinct meters MUST be treated as separate namespaces for the purposes of detecting [duplicate instrument registrations](#duplicate-instrument-registration). -**Status**: [Experimental](../document-status.md) - `Meter` MUST behave +**Status**: [Development](../document-status.md) - `Meter` MUST behave according to the [MeterConfig](#meterconfig) computed during [Meter creation](#meter-creation). If the `MeterProvider` supports updating the [MeterConfigurator](#meterconfigurator), then upon update @@ -845,7 +845,7 @@ the `Meter` MUST be updated to behave according to the new `MeterConfig`. ### MeterConfig -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A `MeterConfig` defines various configurable aspects of a `Meter`'s behavior. It consists of the following parameters: @@ -941,7 +941,7 @@ Meter MUST treat it the same as an empty description string. ### Instrument advisory parameters -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) When a Meter creates an instrument, it SHOULD validate the instrument advisory parameters. If an advisory parameter is not valid, the Meter SHOULD emit an error @@ -1227,11 +1227,11 @@ SHOULD provide at least the following: * The `exporter` to use, which is a `MetricExporter` instance. * The default output `aggregation` (optional), a function of instrument kind. If not configured, the [default aggregation](#default-aggregation) SHOULD be used. * The default output `temporality` (optional), a function of instrument kind. If not configured, the Cumulative temporality SHOULD be used. -* **Status**: [Experimental](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind. If not configured, a default value of 2000 SHOULD be used. -* **Status**: [Experimental](../document-status.md) - The [MetricFilter](#metricfilter) to apply to metrics and attributes during `MetricReader#Collect`. +* **Status**: [Development](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind. If not configured, a default value of 2000 SHOULD be used. +* **Status**: [Development](../document-status.md) - The [MetricFilter](#metricfilter) to apply to metrics and attributes during `MetricReader#Collect`. * Zero of more [MetricProducer](#metricproducer)s (optional) to collect metrics from in addition to metrics from the SDK. -**Status**: [Experimental](../document-status.md) - A `MetricReader` SHOULD provide the [MetricFilter](#metricfilter) to the SDK or registered [MetricProducer](#metricproducer)(s) +**Status**: [Development](../document-status.md) - A `MetricReader` SHOULD provide the [MetricFilter](#metricfilter) to the SDK or registered [MetricProducer](#metricproducer)(s) when calling the `Produce` operation. The [MetricReader.Collect](#collect) method allows general-purpose @@ -1680,11 +1680,11 @@ If a batch of [Metric Points](./data-model.md#metric-points) can include **Parameters:** -**Status**: [Experimental](../document-status.md) `metricFilter`: An optional [MetricFilter](#metricfilter). +**Status**: [Development](../document-status.md) `metricFilter`: An optional [MetricFilter](#metricfilter). ## MetricFilter -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) `MetricFilter` defines the interface which enables the [MetricReader](#metricreader)'s registered [MetricProducers](#metricproducer) or the SDK's [MetricProducer](#metricproducer) to filter aggregated data points diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index 208a6968d49..d824971bc53 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -4,7 +4,7 @@ linkTitle: Prometheus # Metrics Exporter - Prometheus -**Status**: [Experimental](../../document-status.md) +**Status**: [Development](../../document-status.md) A Prometheus Exporter MUST be a [Pull Metric Exporter](../sdk.md#pull-metric-exporter) which responds to HTTP requests with Prometheus metrics in the appropriate format. diff --git a/specification/protocol/file-exporter.md b/specification/protocol/file-exporter.md index 1ebbf157d65..c9b8d800bc8 100644 --- a/specification/protocol/file-exporter.md +++ b/specification/protocol/file-exporter.md @@ -4,7 +4,7 @@ linkTitle: File Exporter # OpenTelemetry Protocol File Exporter -**Status**: [Experimental](../../specification/document-status.md) +**Status**: [Development](../../specification/document-status.md) This document provides a placeholder for specifying an OTLP exporter capable of exporting to either a file or stdout. diff --git a/specification/schemas/file_format_v1.0.0.md b/specification/schemas/file_format_v1.0.0.md index 823cdb5accb..ba1ed4f8713 100644 --- a/specification/schemas/file_format_v1.0.0.md +++ b/specification/schemas/file_format_v1.0.0.md @@ -4,7 +4,7 @@ linkTitle: 1.0.0 # Schema File Format 1.0.0 -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A Schema File is a YAML file that describes the schema of a particular version. It defines the transformations that can be used to convert the telemetry data diff --git a/specification/schemas/file_format_v1.1.0.md b/specification/schemas/file_format_v1.1.0.md index 06fbeeb2c39..b334c5e90e5 100644 --- a/specification/schemas/file_format_v1.1.0.md +++ b/specification/schemas/file_format_v1.1.0.md @@ -4,7 +4,7 @@ linkTitle: 1.1.0 # Schema File Format 1.1.0 -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A Schema File is a YAML file that describes the schema of a particular version. It defines the transformations that can be used to convert the telemetry data diff --git a/specification/semantic-conventions.md b/specification/semantic-conventions.md index 7ef8d4efed7..326749bf793 100644 --- a/specification/semantic-conventions.md +++ b/specification/semantic-conventions.md @@ -1,6 +1,6 @@ # Semantic Conventions -**Status**: [Experimental](document-status.md) +**Status**: [Development](document-status.md) The **Semantic Conventions** define the keys and values which describe commonly observed concepts, protocols, and operations used by applications. @@ -22,7 +22,7 @@ Semantic conventions MUST provide the following attributes: - `exception.stacktrace` - `exception.type` -## Experimental Reserved Attributes +## In-development Reserved Attributes Semantic conventions MUST provide the following attributes: diff --git a/specification/telemetry-stability.md b/specification/telemetry-stability.md index 882f1f93f35..f9b979b1250 100644 --- a/specification/telemetry-stability.md +++ b/specification/telemetry-stability.md @@ -1,6 +1,6 @@ # Telemetry Stability -**Status**: [Experimental](document-status.md) +**Status**: [Development](document-status.md)
Table of Contents diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 4c41bb62d20..4208c4d89d5 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -71,7 +71,7 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. -**Status**: [Experimental](../document-status.md) - The `TracerProvider` MUST +**Status**: [Development](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the configured [TracerConfigurator](#tracerconfigurator), and create a `Tracer` whose behavior conforms to that `TracerConfig`. @@ -80,7 +80,7 @@ a `Tracer` whose behavior conforms to that `TracerConfig`. Configuration ( i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators), [SpanLimits](#span-limits), [`Sampler`](#sampling), -and (**experimental**) [TracerConfigurator](#tracerconfigurator)) MUST be +and (**Development**) [TracerConfigurator](#tracerconfigurator)) MUST be owned by the `TracerProvider`. The configuration MAY be applied at the time of `TracerProvider` creation if appropriate. @@ -95,7 +95,7 @@ reference. #### TracerConfigurator -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A `TracerConfigurator` is a function which computes the [TracerConfig](#tracerconfig) for a [Tracer](#tracer). @@ -158,7 +158,7 @@ make the flush timeout configurable. ## Tracer -**Status**: [Experimental](../document-status.md) - `Tracer` MUST behave +**Status**: [Development](../document-status.md) - `Tracer` MUST behave according to the [TracerConfig](#tracerconfig) computed during [Tracer creation](#tracer-creation). If the `TracerProvider` supports updating the [TracerConfigurator](#tracerconfigurator), then upon update @@ -166,7 +166,7 @@ the `Tracer` MUST be updated to behave according to the new `TracerConfig`. ### TracerConfig -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) A `TracerConfig` defines various configurable aspects of a `Tracer`'s behavior. It consists of the following parameters: diff --git a/specification/trace/tracestate-handling.md b/specification/trace/tracestate-handling.md index e41769174c2..beef94569d8 100644 --- a/specification/trace/tracestate-handling.md +++ b/specification/trace/tracestate-handling.md @@ -4,7 +4,7 @@ linkTitle: TraceState # TraceState Handling -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md) In alignment to the [TraceContext](https://www.w3.org/TR/trace-context/) specification, this section uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234](https://www.w3.org/TR/trace-context/#bib-rfc5234), diff --git a/specification/trace/tracestate-probability-sampling.md b/specification/trace/tracestate-probability-sampling.md index e42b680511e..9b6b10d92d8 100644 --- a/specification/trace/tracestate-probability-sampling.md +++ b/specification/trace/tracestate-probability-sampling.md @@ -4,7 +4,7 @@ linkTitle: Probability Sampling # TraceState: Probability Sampling -**Status**: [Experimental](../document-status.md) +**Status**: [Development](../document-status.md)
Table of Contents diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 08a9c931bf7..c855656fe6f 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -9,7 +9,7 @@ - [Design goals](#design-goals) - [Signal lifecycle](#signal-lifecycle) - * [Experimental](#experimental) + * [Development](#development) * [Stable](#stable) + [API Stability](#api-stability) - [Extending Existing API Calls](#extending-existing-api-calls) @@ -61,36 +61,40 @@ A library that imports the OpenTelemetry API should never become incompatible wi Theoretically, APIs can be deprecated and eventually removed, but this is a process measured in years and we have no plans to do so. **Allow for multiple levels of package stability within the same release of an OpenTelemetry component.** -Provide maintainers a clear process for developing new, experimental [signals](glossary.md#signals) alongside stable signals. +Provide maintainers a clear process for developing new [signals](glossary.md#signals) in Development status alongside stable signals. Different packages within the same release may have different levels of stability. -This means that an implementation wishing to release stable tracing today MUST ensure that experimental metrics are factored out in such a way that breaking changes to metrics API do not destabilize the trace API packages. +This means that an implementation wishing to release stable tracing today MUST ensure that in-development metrics are factored out in such a way that breaking changes to metrics API do not destabilize the trace API packages. ## Signal lifecycle -The development of each signal follows a lifecycle: experimental, stable, deprecated, removed. +The development of each signal follows a lifecycle: development, stable, deprecated, removed. The infographic below shows an example of the lifecycle of an API component. ![API Lifecycle](../internal/img/api-lifecycle.png) -### Experimental +### Development -Signals start as **experimental**, which covers alpha, beta, and release candidate versions of the signal. -While signals are experimental, breaking changes and performance issues MAY occur. +Signals start in **Development** status as defined by +[OTEP 0232](https://github.com/open-telemetry/oteps/blob/main/text/0232-maturity-of-otel.md#explanation). +While signals are in development, breaking changes and performance issues MAY occur. Components SHOULD NOT be expected to be feature-complete. -In some cases, the experiment MAY be discarded and removed entirely. -Long-term dependencies SHOULD NOT be taken against experimental signals. +In some cases, the signal in Development MAY be discarded and removed entirely. +Long-term dependencies SHOULD NOT be taken against signals in Development. -OpenTelemetry clients MUST be designed in a manner that allows experimental signals to be created without breaking the stability guarantees of existing signals. +OpenTelemetry clients MUST be designed in a manner that allows signals in Development to be created without breaking the stability guarantees of existing signals. -OpenTelemetry clients MUST NOT be designed in a manner that breaks existing users when a signal transitions from experimental to stable. This would punish users of the release candidate, and hinder adoption. +OpenTelemetry clients MUST NOT be designed in a manner that breaks existing users when a signal transitions from Development to Stable. This would punish users of the release candidate, and hinder adoption. -Terms which denote stability, such as "experimental," MUST NOT be used as part of a directory or import name. -Package **version numbers** MAY include a suffix, such as -alpha, -beta, -rc, or -experimental, to differentiate stable and experimental packages. +Terms which denote stability, such as "development", MUST NOT be used as part of a directory or import name. +Package **version numbers** MAY include a suffix, such as -alpha, -beta, -rc, or -development, to differentiate packages in different statuses. + +Note that "Development" status was previously called "Experimental" in this repository. +Any uses of "Experimental" should be treated same as "Development". ### Stable -Once an experimental signal has gone through rigorous beta testing, it MAY transition to **stable**. +Once a signal in Development has gone through rigorous testing, it MAY transition to **Stable**. Long-term dependencies MAY now be taken against this signal. All signal components MAY become stable together, or MAY transition to stability component-by-component. The API MUST become stable before the other components. @@ -332,8 +336,8 @@ For example, it is fine to have `opentelemetry-python-api` at v1.2.8 when `opent * Language implementations have version numbers which are independent of the specification they implement. For example, it is fine for v1.8.2 of `opentelemetry-python-api` to implement v1.1.1 of the specification. -**Exception:** in some languages, package managers may react poorly to experimental packages having a version higher than 0.X. -In these cases, experimental signals MAY version independently from stable signals, in order to retain a 0.X version number. +**Exception:** in some languages, package managers may react poorly to unstable packages having a version higher than 0.X. +In these cases, signals in Development MAY version independently from stable signals, in order to retain a 0.X version number. When a signal becomes stable, the version MUST be bumped to match the other stable signals in the release. ### Major version bump @@ -347,9 +351,9 @@ Most changes to OpenTelemetry clients result in a minor version bump. * New backward-compatible functionality added to any component. * Breaking changes to internal SDK components. -* Breaking changes to experimental signals. -* New experimental signals are added. -* Experimental signals become stable. +* Breaking changes to in-development signals. +* New signals in Development are added. +* Signals in Development become stable. * Stable signals are deprecated. ### Patch version bump