Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add lifecycle statuses to all documents #1385

Merged
merged 8 commits into from
Feb 4, 2021
Merged

Add lifecycle statuses to all documents #1385

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d6814a6
Add lifecycle statues to all documents
tedsuo Jan 27, 2021
1b78059
fix relative links
tedsuo Jan 28, 2021
752f1bc
add mixed status
tedsuo Feb 2, 2021
49be39d
Mark OTLP/HTTP as experimental
tedsuo Feb 2, 2021
3c8794d
typo
tedsuo Feb 3, 2021
2c5872c
lint
tedsuo Feb 3, 2021
7aa410e
more lint
tedsuo Feb 3, 2021
473e340
Merge branch 'main' into lifecycle_statuses
carlosalberto Feb 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion specification/baggage/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Baggage API

**Status**: [Feature-freeze](../document-status.md).
**Status**: [Stable, Feature-freeze](../document-status.md)

<details>
<summary>
Expand Down
2 changes: 2 additions & 0 deletions specification/common/attribute-and-label-naming.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Attribute and Label Naming

**Status**: [Experimental](../document-status.md)

<details>
<summary>
Table of Contents
Expand Down
2 changes: 1 addition & 1 deletion specification/common/common.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Common specification concepts

**Status**: [Feature-freeze](../document-status.md).
**Status**: [Stable, Feature-freeze](../document-status.md)

<details>
<summary>
Expand Down
2 changes: 2 additions & 0 deletions specification/context/api-propagators.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Propagators API

**Status**: [Stable, Feature-Freeze](../document-status.md)
tedsuo marked this conversation as resolved.
Show resolved Hide resolved

<details>
<summary>
Table of Contents
Expand Down
2 changes: 1 addition & 1 deletion specification/context/context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Context

**Status**: [Feature-freeze](../document-status.md).
**Status**: [Stable, Feature-freeze](../document-status.md).

<details>
<summary>
Expand Down
16 changes: 14 additions & 2 deletions specification/document-status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,19 @@ shown immediately after the document title. When present, the "Status" applies
to the individual document only and not to the entire specification or any other
documents. The following table describes what the statuses mean.

## Lifecycle status

The support guarantees and allowed changes are governed by the lifecycle of the document.Lifecycle stages are defined in the [Versioning and Stability](versioning-and-stability.md) document.

|Status |Explanation|
|--------------------|-----------|
|No explicit "Status"|Working draft, can change any time.|
|Feature-freeze |Document is no longer accepting new substantial changes, except when such changes are necessary to resolve a fundamental problem or inconsistency in the specification. Editorial changes are accepted. The document and the area it describes are considered feature-complete for the version of the specification the document targets. The document in this status is ready for implementation.|
|No explicit "Status"|Equivalent to Experimental.|
|Experimental |Breaking changes are allowed.|
|Stable |Breaking changes are not longer allowed. See [stability guarantees](versioning-and-stability.md#stable) for details.|
tedsuo marked this conversation as resolved.
Show resolved Hide resolved
|Deprecated |Changes are no longer allowed, except for editorial changes.|

## 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.

Feature freeze is separate from a lifecycle status. The lifecycle represents the support requirements for the document, feature freeze only indicates the current focus of the specification community. The feature freeze label may be applied to a document at any lifecycle stage. By definition, deprecated documents have a feature freeze in place.
2 changes: 2 additions & 0 deletions specification/logs/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Log Data Model

**Status**: [Experimental](../document-status.md)

* [Design Notes](#design-notes)
* [Requirements](#requirements)
* [Field Kinds](#field-kinds)
Expand Down
2 changes: 2 additions & 0 deletions specification/logs/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# OpenTelemetry Logging Overview

**Status**: [Experimental](../document-status.md)

* [Introduction](#introduction)
* [Limitations of non-OpenTelemetry Solutions](#limitations-of-non-opentelemetry-solutions)
* [OpenTelemetry Solution](#opentelemetry-solution)
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Metrics API

**Status**: [Experimental](../document-status.md)

<!-- toc -->

- [Overview](#overview)
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Metrics SDK

**Status**: [Experimental](../document-status.md)

TODO: TOC

## Purpose
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/semantic_conventions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Metrics Semantic Conventions

**Status**: [Experimental](../../document-status.md)

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

<!-- toc -->
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/semantic_conventions/http-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# General

**Status**: [Experimental](../../document-status.md)

The conventions described in this section are HTTP specific. When HTTP operations occur,
metric events about those operations will be generated and reported to provide insight into the
operations. By adding HTTP labels to metric events it allows for finely tuned filtering.
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/semantic_conventions/openmetrics-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Guidance for Interoperating with OpenMetrics

**Status**: [Experimental](../../document-status.md)

**Note:** This document is work in progress and will be updated as the
OpenMetrics specification further develops.

Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/semantic_conventions/process-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic Conventions for OS Process Metrics

**Status**: [Experimental](../../document-status.md)

This document describes instruments and labels for common OS process level
metrics in OpenTelemetry. Also consider the [general metric semantic
conventions](README.md#general-metric-semantic-conventions) when creating
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/semantic_conventions/rpc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# General RPC conventions

**Status**: [Experimental](../../document-status.md)

The conventions described in this section are RPC specific. When RPC operations
occur, metric events about those operations will be generated and reported to
provide insight into those operations. By adding RPC labels to metric events
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/semantic_conventions/runtime-environment-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic Conventions for Runtime Environment Metrics

**Status**: [Experimental](../../document-status.md)

This document includes semantic conventions for runtime environment level
metrics in OpenTelemetry. Also consider the [general
metric](README.md#general-metric-semantic-conventions), [system
Expand Down
2 changes: 2 additions & 0 deletions specification/metrics/semantic_conventions/system-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic Conventions for System Metrics

**Status**: [Experimental](../../document-status.md)

This document describes instruments and labels for common system level
metrics in OpenTelemetry. Consider the [general metric semantic
conventions](README.md#general-metric-semantic-conventions) when creating
Expand Down
2 changes: 2 additions & 0 deletions specification/protocol/exporter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# OpenTelemetry Protocol Exporter

**Status**: [Stable](../document-status.md)

This document specifies the configuration options available to the OpenTelemetry Protocol ([OTLP](https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md)) Exporter as well as the retry behavior.

## Configuration Options
Expand Down
2 changes: 2 additions & 0 deletions specification/protocol/otlp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# OpenTelemetry Protocol Specification

**Status**: [Stable](../document-status.md)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is are discussion in this document about JSON being supported for OTLP/HTTP which I think we are not yet ready to make it stable. How can we solve that?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I marked OTLP/HTTP as experimental. The JSON and binary formats for HTTP were intermixed; if we want proto over OTLP/HTTP to be stable this section should be re-written.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OTLP/HTTP-Protobufs are stable. Only OTLP/HTTP-JSON is unstable. Please file a TODO to fix this.

We should probably also note that only Traces are currently stable. Looks like we are going to end up with a lot of clarifications for our stability declarations in this file to be true, but that's the reality.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @tigrannajaryan. I created a follow up issue: #1397

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bogdandrutu Please review. I think that we are ready to merge this and tune the OTLP/JSON part in the related follow up.


OpenTelemetry Protocol (OTLP) specification describes the encoding, transport,
and delivery mechanism of telemetry data between telemetry sources, intermediate
nodes such as collectors and telemetry backends.
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Resource SDK

**Status**: [Stable](../document-status.md)

A [Resource](../overview.md#resources) is an immutable representation of the entity producing
telemetry as [Attributes](../common/common.md#attributes).
For example, a process producing telemetry that is running in a
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Resource Semantic Conventions

**Status**: [Experimental](../../document-status.md)
tedsuo marked this conversation as resolved.
Show resolved Hide resolved

This document defines standard attributes for resources. These attributes are typically used in the [Resource](../sdk.md) and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from
[OpenCensus Resource standard](https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md).

Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/cloud.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Cloud

**Status**: [Experimental](../../document-status.md)

**type:** `cloud`

**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS).
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/cloud_provider/aws/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# AWS Semantic Conventions

**Status**: [Experimental](../../../../document-status.md)

This directory defines standards for resource attributes that only apply to Amazon
Web Services (AWS) resources. If an attribute could apply to resources from more than one cloud
provider (like account ID, operating system, etc), it belongs in the parent
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/cloud_provider/aws/ecs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# AWS ECS

**Status**: [Experimental](../../../../document-status.md)

**type:** `aws.ecs`

**Description:** Resources used by AWS Elastic Container Service (ECS).
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/cloud_provider/aws/logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# AWS Logs

**Status**: [Experimental](../../../../document-status.md)

**Type:** `aws.log`

**Description:** Log attributes for Amazon Web Services.
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/container.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Container

**Status**: [Experimental](../../document-status.md)

**type:** `container`

**Description:** A container instance.
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/deployment_environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Deployment

**Status**: [Experimental](../../document-status.md)

**type:** `deployment`

**Description:** The software deployment.
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/faas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Function as a Service

**Status**: [Experimental](../../document-status.md)

**type:** `faas`

**Description:** A serverless instance.
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/host.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Host

**Status**: [Experimental](../../document-status.md)

**type:** `host`

**Description:** A host is defined as a general computing instance.
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/k8s.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Kubernetes

**Status**: [Experimental](../../document-status.md)

Useful resources to understand Kubernetes objects and metadata:

* [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/os.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Operating System

**Status**: [Experimental](../../document-status.md)

**type:** `os`

**Description**: The operating system (OS) on which the process represented by this resource is running.
Expand Down
2 changes: 2 additions & 0 deletions specification/resource/semantic_conventions/process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Process and process runtime resources

**Status**: [Experimental](../../document-status.md)

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

<!-- toc -->
Expand Down
2 changes: 1 addition & 1 deletion specification/trace/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Tracing API

**Status**: [Feature-freeze](../document-status.md).
**Status**: [Stable, Feature-freeze](../document-status.md)

<details>
<summary>
Expand Down
2 changes: 2 additions & 0 deletions specification/trace/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Tracing SDK

**Status**: [Stable](../document-status.md)

<details>

<summary>Table of Contents</summary>
Expand Down
2 changes: 2 additions & 0 deletions specification/trace/sdk_exporters/jaeger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# OpenTelemetry to Jaeger Transformation

**Status**: [Stable](../../document-status.md)

This document defines the transformation between OpenTelemetry and Jaeger Spans.
Jaeger accepts spans in two formats:

Expand Down
2 changes: 2 additions & 0 deletions specification/trace/sdk_exporters/zipkin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# OpenTelemetry to Zipkin Transformation

**Status**: [Stable](../../document-status.md)

This document defines the transformation between OpenTelemetry and Zipkin Spans.
Zipkin's v2 API is defined in the
[zipkin.proto](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto)
Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Trace Semantic Conventions

**Status**: [Experimental](../../document-status.md)

In OpenTelemetry spans can be created freely and it’s up to the implementor to
annotate them with attributes specific to the represented operation. Spans
represent specific operations in and between systems. Some of these operations
Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/database.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic conventions for database client calls

**Status**: [Experimental](../../document-status.md)

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

<!-- toc -->
Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/exceptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic Conventions for Exceptions

**Status**: [Experimental](../../document-status.md)

This document defines semantic conventions for recording application
exceptions.

Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/faas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic conventions for FaaS spans

**Status**: [Experimental](../../document-status.md)

This document defines how to describe an instance of a function that runs without provisioning
or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with spans.

Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic conventions for HTTP spans

**Status**: [Experimental](../../document-status.md)

This document defines semantic conventions for HTTP client and server Spans.
They can be used for http and https schemes
and various HTTP versions like 1.1, 2 and SPDY.
Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Messaging systems

**Status**: [Experimental](../../document-status.md)

<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->

<!-- toc -->
Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/rpc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Semantic conventions for RPC spans

**Status**: [Experimental](../../document-status.md)

This document defines how to describe remote procedure calls
(also called "remote method invocations" / "RMI") with spans.

Expand Down
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/span-general.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# General attributes

**Status**: [Experimental](../../document-status.md)

The attributes described in this section are not specific to a particular operation but rather generic.
They may be used in any Span they apply to.
Particular operations may refer to or require some of these attributes.
Expand Down