Merge branch 'main' into MSNev/AttributeSupport

open-telemetry · Jun 28, 2022 · 8bb0e81 · 8bb0e81
2 parents a28546c + 42266f5
commit 8bb0e81
Show file tree

Hide file tree

Showing 31 changed files with 174 additions and 48 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,8 +11,15 @@ release.
 
 ### Traces
 
+- Clarify the return of `Export(batch)` in the Batch Span Processor and exporter
+  concurrency ([#2452](https://github.com/open-telemetry/opentelemetry-specification/pull/2452))
+
 ### Metrics
 
+- Add experimental `OTEL_EXPORTER_OTLP_DEFAULT_HISTOGRAM_AGGREGATION` variable for
+  configuring default histogram aggregation of OTLP metric exporter
+  ([#2619](https://github.com/open-telemetry/opentelemetry-specification/pull/2619)).
+
 ### Logs
 
 ### Resource
@@ -21,10 +28,16 @@ release.
 
 - Add `net.app.protocol.*` attributes
   ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)).
+- Add network metrics to process semantic conventions
+  ([#2556](https://github.com/open-telemetry/opentelemetry-specification/pull/2556))
 - Adopt attribute requirement levels in semantic conventions
   ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594))
 - Add semantic conventions for GraphQL
   ([#2456](https://github.com/open-telemetry/opentelemetry-specification/pull/2456))
+- Change `cloudevents.event_spec_version` and `cloudevents.event_type` level from `required` to `recommended`
+  ([#2618](https://github.com/open-telemetry/opentelemetry-specification/pull/2618))
+- Change `faas.document.time` and `faas.time` level from `required` to `recommended`
+  ([#2627](https://github.com/open-telemetry/opentelemetry-specification/pull/2627))
 
 ### Compatibility
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -170,13 +170,17 @@ The following diagram shows the initial triaging of new issues.
   the 3 responses:
   - Yes, this is a good issue and we want to work on it.
   - Maybe, this issue needs to be clarified and/or others have to be pulled in
-    before we can make a decision.
+    before we can make a decision. More information may be requested from the
+    issue author or others.
   - No, this issue should not be accepted. This can happen when the issue is a
     duplicate, was discussed and rejected in the past, is out of the project
     scope, etc. The assignee labels the issue "won't do", closes it and provides
     the reason for closing. The issue author has the choice to appeal the
     decision, in which case the issue is reopened and the assignee asks other
     spec approvers to help triage and facilitate the discussion.
+  - As a result of triaging one of the 3 labels must be applied to the issue:
+    `triaged-accepted`, `triaged-needmoreinfo`, `triaged-rejected`. Absence
+    of the label indicates that the issue still needs the first response.
 - If the first response is Yes, the assignee decides if they are the right
   person to work on the issue long-term. If not, they will look for another
   contributor who can work on the issue and re-assign to them, label the issue

diff --git a/semantic_conventions/trace/cloudevents.yaml b/semantic_conventions/trace/cloudevents.yaml
@@ -20,13 +20,11 @@ groups:
         examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ]
       - id: event_spec_version
         type: string
-        requirement_level: required
         brief: >
           The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses.
         examples: '1.0'
       - id: event_type
         type: string
-        requirement_level: required
         brief: >
           The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence.
         examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2']

diff --git a/semantic_conventions/trace/faas.yaml b/semantic_conventions/trace/faas.yaml
@@ -73,7 +73,6 @@ groups:
         brief: 'Describes the type of the operation that was performed on the data.'
       - id: time
         type: string
-        requirement_level: required
         brief: >
           A string containing the time when the data was accessed in the
           [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
@@ -111,7 +110,6 @@ groups:
     attributes:
       - id: time
         type: string
-        requirement_level: required
         brief: >
           A string containing the function invocation time in the
           [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -84,7 +84,7 @@ formats is required. Implementing more than one format is optional.
 | [SpanLimits](specification/trace/sdk.md#span-limits)                                             | X        | +   | +    |     | +      | +    | +      | +   |      | -   |      | +     |
 | [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) |          |     | +    |     | +      | +    | +      | +   | +    | +   | +    |       |
 | [Attribute Limits](specification/common/README.md#attribute-limits)                              | X        |     | +    |     |        |      | +      | +   |      |     |      |       |
-| Fetch InstrumentationScope from ReadableSpan                                                     |          |     | +    |     |        |      |        |     |      |     |      |       |
+| Fetch InstrumentationScope from ReadableSpan                                                     |          |     | +    |     |        |      |        | +   |      |     |      |       |
 
 ## Baggage
 

diff --git a/specification/logs/overview.md → specification/logs/README.md b/specification/logs/overview.md → specification/logs/README.md
@@ -1,3 +1,8 @@
+<!---
+linkTitle: Logs
+aliases: [/docs/reference/specification/logs/overview]
+--->
+
 # OpenTelemetry Logging Overview
 
 **Status**: [Experimental](../document-status.md)

diff --git a/specification/logs/logging-library-sdk.md b/specification/logs/logging-library-sdk.md
@@ -8,7 +8,7 @@ This document contains the first cut from the
 This specification defines how the OpenTelemetry Logging Library SDK exposes its
 functionality to authors of extensions to language-specific 3rd party logging
 libraries and to end users that want to produce logs in the
-[OpenTelemetry manner](overview.md).
+[OpenTelemetry manner](README.md).
 
 The specification defines SDK elements that to some extent mirror the
 OpenTelemetry [Trace SDK](../trace/sdk.md). This ensures uniformity and
@@ -120,7 +120,7 @@ Methods:
 An Appender implementation can be used to allow emitting log records via
 OpenTelemetry Logging Library exporters. This approach is typically used for
 applications which are fine with changing the log transport and is
-[one of the supported](overview.md#direct-to-collector) log collection
+[one of the supported](README.md#direct-to-collector) log collection
 approaches.
 
 The Appender implementation will typically acquire a LogEmitter from the global

diff --git a/specification/metrics/README.md b/specification/metrics/README.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: Metrics
+--->
+
 # OpenTelemetry Metrics
 
 <details>

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: API
+--->
+
 # Metrics API
 
 **Status**: [Stable](../document-status.md)

diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: Data Model
+--->
+
 # Metrics Data Model
 
 **Status**: [Mixed](../document-status.md)

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: SDK
+--->
+
 # Metrics SDK
 
 **Status**: [Mixed](../document-status.md)
@@ -19,11 +23,11 @@
     + [Last Value Aggregation](#last-value-aggregation)
       - [Histogram Aggregation common behavior](#histogram-aggregation-common-behavior)
     + [Explicit Bucket Histogram Aggregation](#explicit-bucket-histogram-aggregation)
-    + [Exponential Histogram Aggregation](#exponential-histogram-aggregation)
-      - [Exponential Histogram Aggregation: Handle all normal values](#exponential-histogram-aggregation-handle-all-normal-values)
-      - [Exponential Histogram Aggregation: Support a minimum and maximum scale](#exponential-histogram-aggregation-support-a-minimum-and-maximum-scale)
-      - [Exponential Histogram Aggregation: Use the maximum scale for single measurements](#exponential-histogram-aggregation-use-the-maximum-scale-for-single-measurements)
-      - [Exponential Histogram Aggregation: Maintain the ideal scale](#exponential-histogram-aggregation-maintain-the-ideal-scale)
+    + [Exponential Bucket Histogram Aggregation](#exponential-bucket-histogram-aggregation)
+      - [Exponential Bucket Histogram Aggregation: Handle all normal values](#exponential-bucket-histogram-aggregation-handle-all-normal-values)
+      - [Exponential Bucket Histogram Aggregation: Support a minimum and maximum scale](#exponential-bucket-histogram-aggregation-support-a-minimum-and-maximum-scale)
+      - [Exponential Bucket Histogram Aggregation: Use the maximum scale for single measurements](#exponential-bucket-histogram-aggregation-use-the-maximum-scale-for-single-measurements)
+      - [Exponential Bucket Histogram Aggregation: Maintain the ideal scale](#exponential-bucket-histogram-aggregation-maintain-the-ideal-scale)
   * [Observations inside asynchronous callbacks](#observations-inside-asynchronous-callbacks)
   * [Resolving duplicate instrument registration conflicts](#resolving-duplicate-instrument-registration-conflicts)
 - [Attribute limits](#attribute-limits)
@@ -346,7 +350,7 @@ The SDK MUST provide the following `Aggregation` to support the
 
 The SDK MAY provide the following `Aggregation`:
 
-- [Exponential Histogram Aggregation](./sdk.md#exponential-histogram-aggregation)
+- [Exponential Bucket Histogram Aggregation](./sdk.md#exponential-bucket-histogram-aggregation)
 
 #### Drop Aggregation
 
@@ -435,7 +439,7 @@ bound (except at positive infinity).  A measurement is defined to fall
 into the greatest-numbered bucket with boundary that is greater than
 or equal to the measurement.
 
-#### Exponential Histogram Aggregation
+#### Exponential Bucket Histogram Aggregation
 
 The Exponential Histogram Aggregation informs the SDK to collect data
 for the [Exponential Histogram Metric
@@ -487,7 +491,7 @@ either:
 1. The maximum supported scale, generally used for single-value histogram Aggregations where scale is not otherwise constrained
 2. The largest value of scale such that no more than the maximum number of buckets are needed to represent the full range of input data in either of the positive or negative ranges.
 
-##### Exponential Histogram Aggregation: Handle all normal values
+##### Exponential Bucket Histogram Aggregation: Handle all normal values
 
 Implementations are REQUIRED to accept the entire normal range of IEEE
 floating point values (i.e., all values except for +Inf, -Inf and NaN
@@ -500,18 +504,18 @@ values do not map into a valid bucket.
 Implementations MAY round subnormal values away from zero to the
 nearest normal value.
 
-##### Exponential Histogram Aggregation: Support a minimum and maximum scale
+##### Exponential Bucket Histogram Aggregation: Support a minimum and maximum scale
 
 The implementation MUST maintain reasonable minimum and maximum scale
 parameters that the automatic scale parameter will not exceed.
 
-##### Exponential Histogram Aggregation: Use the maximum scale for single measurements
+##### Exponential Bucket Histogram Aggregation: Use the maximum scale for single measurements
 
 When the histogram contains not more than one value in either of the
 positive or negative ranges, the implementation SHOULD use the maximum
 scale.
 
-##### Exponential Histogram Aggregation: Maintain the ideal scale
+##### Exponential Bucket Histogram Aggregation: Maintain the ideal scale
 
 Implementations SHOULD adjust the histogram scale as necessary to
 maintain the best resolution possible, within the constraint of

diff --git a/specification/metrics/sdk_exporters/README.md b/specification/metrics/sdk_exporters/README.md
@@ -0,0 +1,5 @@
+<!---
+linkTitle: Exporters
+--->
+
+# Metrics Exporters
diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: In-memory
+--->
+
 # OpenTelemetry Metrics Exporter - In-memory
 
 **Status**: [Stable](../../document-status.md)

diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md
@@ -1,5 +1,13 @@
+<!---
+linkTitle: OTLP
+--->
+
 # OpenTelemetry Metrics Exporter - OTLP
 
+**Status**: [Mixed](../../document-status.md)
+
+## General
+
 **Status**: [Stable](../../document-status.md)
 
 OTLP Metrics Exporter is a [Push Metric
@@ -19,18 +27,32 @@ variable](../../sdk-environment-variables.md#exporter-selection)),
 then by default:
 
 * The exporter MUST be paired with a [periodic exporting
-MetricReader](../sdk.md#periodic-exporting-metricreader).
+  MetricReader](../sdk.md#periodic-exporting-metricreader).
 * The exporter MUST configure the default aggregation temporality on the
   basis of instrument kind using the
   `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` variable as described
-  below, otherwise the exporter MUST use Cumulative as the default
-  aggregation temporality for all instrument kinds.
+  below.
+* The exporter MUST configure the default aggregation on the basis of instrument kind using
+  the `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` variable as described below if it is implemented.
+
+## Additional Configuration
+
+**Status**: [Mixed](../../document-status.md)
+
+| Name                                                | Status       | Description                                                         | Default                     |
+|-----------------------------------------------------|--------------|---------------------------------------------------------------------|-----------------------------|
+| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Stable       | The aggregation temporality to use on the basis of instrument kind. | `cumulative`                |
+| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION`  | Experimental | The default aggregation to use for histogram instruments.           | `explicit_bucket_histogram` |
+
+The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` are:
+
+* `cumulative`: Choose cumulative aggregation temporality for all instrument kinds.
+* `delta`: Choose Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds, choose
+  Cumulative aggregation for UpDownCounter and Asynchronous UpDownCounter instrument kinds.
 
-The `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` environment variable
-defines the default aggregation temporality policy
-to use on the basis of instrument kind.  The recognized (case-insensitive) values are:
+The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` are:
 
-| Value      | Definition                                                                                                    |
-|------------|---------------------------------------------------------------------------------------------------------------|
-| CUMULATIVE | Choose Cumulative aggregation temporality for all instrument kinds.                                           |
-| DELTA      | Choose Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds, choose Cumulative aggregation temporality for UpDownCounter and Asynchronous UpDownCounter instrument kinds. |
+* `explicit_bucket_histogram`:
+  Use [Explicit Bucket Histogram Aggregation](../sdk.md#explicit-bucket-histogram-aggregation).
+* `exponential_bucket_histogram`:
+  Use [Exponential Bucket Histogram Aggregation](../sdk.md#exponential-bucket-histogram-aggregation).
diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: Prometheus
+--->
+
 # OpenTelemetry Metrics Exporter - Prometheus
 
 **Status**: [Experimental](../../document-status.md)

diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: Stdout
+--->
+
 # OpenTelemetry Metrics Exporter - Standard output
 
 **Status**: [Stable](../../document-status.md)

diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md
@@ -1,9 +1,11 @@
+<!---
+linkTitle: Semantic Conventions
+--->
+
 # Metrics Semantic Conventions
 
 **Status**: [Experimental](../../document-status.md)
 
-<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
-
 <!-- toc -->
 
 - [General Guidelines](#general-guidelines)

diff --git a/specification/metrics/semantic_conventions/database-metrics.md b/specification/metrics/semantic_conventions/database-metrics.md
@@ -1,4 +1,8 @@
-# General
+<!---
+linkTitle: Database
+--->
+
+# Semantic Conventions for Database Metrics
 
 **Status**: [Experimental](../../document-status.md)
 

diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md
@@ -1,4 +1,8 @@
-# General
+<!---
+linkTitle: FaaS
+--->
+
+# Semantic Conventions for FaaS Metrics
 
 **Status**: [Experimental](../../document-status.md)
 

diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
@@ -1,4 +1,8 @@
-# General
+<!---
+linkTitle: HTTP
+--->
+
+# Semantic Conventions for HTTP Metrics
 
 **Status**: [Experimental](../../document-status.md)
 

diff --git a/specification/metrics/semantic_conventions/instrumentation/README.md b/specification/metrics/semantic_conventions/instrumentation/README.md
@@ -0,0 +1 @@
+# Instrumentation
diff --git a/specification/metrics/semantic_conventions/instrumentation/kafka.md b/specification/metrics/semantic_conventions/instrumentation/kafka.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: Kafka
+--->
+
 # Instrumenting Kafka
 
 **Status**: [Experimental](../../../document-status.md)

diff --git a/specification/metrics/semantic_conventions/openmetrics-guidelines.md b/specification/metrics/semantic_conventions/openmetrics-guidelines.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: OpenMetrics
+--->
+
 # Guidance for Interoperating with OpenMetrics
 
 **Status**: [Experimental](../../document-status.md)

diff --git a/specification/metrics/semantic_conventions/process-metrics.md b/specification/metrics/semantic_conventions/process-metrics.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: Process
+--->
+
 # Semantic Conventions for OS Process Metrics
 
 **Status**: [Experimental](../../document-status.md)
@@ -34,6 +38,7 @@ Below is a table of Process metric instruments.
 | `process.memory.usage`    | UpDownCounter                                     | By    | The amount of physical memory in use.                                                                                               |                                                                                                                                                                                                 |
 | `process.memory.virtual`  | UpDownCounter                                     | By    | The amount of committed virtual memory.                                                                                             |                                                                                                                                                                                                 |
 | `process.disk.io`         | Counter                                           | By    | Disk bytes transferred.                                                                                                             | `direction` SHOULD be one of: `read`, `write`                                                                                                                                                   |
+| `process.network.io`      | Counter                                           | By    | Network bytes transferred.                                                                                                          | `direction` SHOULD be one of: `receive`, `transmit`                                                                                                                                           |
 
 ## Attributes
 

diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: RPC
+--->
+
 # General RPC conventions
 
 **Status**: [Experimental](../../document-status.md)

diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md
@@ -1,3 +1,7 @@
+<!---
+linkTitle: Runtime Environment
+--->
+
 # Semantic Conventions for Runtime Environment Metrics
 
 **Status**: [Experimental](../../document-status.md)