Merge branch 'main' into define-http-sampling-attributes

CHANGELOG.md

@@ -11,8 +11,37 @@ release.
 
 ### Traces
 
+### Metrics
+
+- Add optional min / max fields to histogram data model.
+  ([#1915](https://github.com/open-telemetry/opentelemetry-specification/pull/1915))
+
+### Logs
+
+### Resource
+
+### Semantic Conventions
+
+### Compatibility
+
+### OpenTelemetry Protocol
+
+- Make OTLP/HTTP the recommended default transport ([#1969](https://github.com/open-telemetry/opentelemetry-specification/pull/1969))
+
+### SDK Configuration
+
+## v1.7.0 (2021-09-30)
+
+### Context
+
+- No changes.
+
+### Traces
+
 - Prefer global user defined limits over model-sepcific default values.
   ([#1893](https://github.com/open-telemetry/opentelemetry-specification/pull/1893))
+- Generalize the "message" event to apply to all RPC systems not just gRPC
+  ([#1914](https://github.com/open-telemetry/opentelemetry-specification/pull/1914))
 
 ### Metrics
 
@@ -26,10 +55,16 @@ release.
   [#1888](https://github.com/open-telemetry/opentelemetry-specification/pull/1888),
   [#1912](https://github.com/open-telemetry/opentelemetry-specification/pull/1912),
   [#1913](https://github.com/open-telemetry/opentelemetry-specification/pull/1913),
-  [#1938](https://github.com/open-telemetry/opentelemetry-specification/pull/1938))
+  [#1938](https://github.com/open-telemetry/opentelemetry-specification/pull/1938),
+  [#1958](https://github.com/open-telemetry/opentelemetry-specification/pull/1958))
+- Add FaaS metrics semantic conventions ([#1736](https://github.com/open-telemetry/opentelemetry-specification/pull/1736))
+- Update env variable values to match other env variables
+  ([#1965](https://github.com/open-telemetry/opentelemetry-specification/pull/1965))
 
 ### Logs
 
+- No changes.
+
 ### Resource
 
 - Exempt Resource from attribute limits.
@@ -52,19 +87,31 @@ release.
   ([#1890](https://github.com/open-telemetry/opentelemetry-specification/pull/1890))
 - Add HTTP request and response headers semantic conventions.
   ([#1898](https://github.com/open-telemetry/opentelemetry-specification/pull/1898))
+- Add `k8s.container.restart_count` Resource attribute.
+  ([#1945](https://github.com/open-telemetry/opentelemetry-specification/pull/1945))
 - Define http tracing attributes provided at span creation time
   ([#1919](https://github.com/open-telemetry/opentelemetry-specification/pull/1916))
 
 ### Compatibility
 
+- No changes.
+
 ### OpenTelemetry Protocol
 
 - Add environment variables for configuring the OTLP exporter protocol (`grpc`, `http/protobuf`, `http/json`) ([#1880](https://github.com/open-telemetry/opentelemetry-specification/pull/1880))
+- Specify the behavior of the OTLP endpoint variables for OTLP/HTTP more strictly
+  ([#1975](https://github.com/open-telemetry/opentelemetry-specification/pull/1975)).
+- Allow implementations to use their own default for OTLP compression, with `none` denotating no compression
+  ([#1923](https://github.com/open-telemetry/opentelemetry-specification/pull/1923))
+- Clarify OTLP server components MUST support none/gzip compression
+  ([#1955](https://github.com/open-telemetry/opentelemetry-specification/pull/1955))
+- Change OTLP/HTTP port from 4317 to 4318 ([#1970](https://github.com/open-telemetry/opentelemetry-specification/pull/1970))
 
 ### SDK Configuration
 
 - Change default value for OTEL_EXPORTER_JAEGER_AGENT_PORT to 6831.
   ([#1812](https://github.com/open-telemetry/opentelemetry-specification/pull/1812))
+- See also the changes for OTLP configuration listed under "OpenTelemetry Protocol" above.
 
 ## v1.6.0 (2021-08-06)
 
@@ -135,7 +182,6 @@ release.
 
 - Clarify the limit on the instrument unit.
   ([#1762](https://github.com/open-telemetry/opentelemetry-specification/pull/1762))
-- Add FaaS metrics semantic conventions ([#1736](https://github.com/open-telemetry/opentelemetry-specification/pull/1736))  
 
 ### Logs
 

schemas/1.7.0

@@ -0,0 +1,7 @@
+file_format: 1.0.0
+schema_url: https://opentelemetry.io/schemas/1.7.0
+versions:
+  1.7.0:
+  1.6.1:
+  1.5.0:
+  1.4.0:

semantic_conventions/resource/k8s.yaml

@@ -63,6 +63,13 @@ groups:
         brief: >
           The name of the Container in a Pod template.
         examples: ['redis']
+      - id: restart_count
+        type: int
+        brief: >
+          Number of times the container was restarted. This attribute can be
+          used to identify a particular container (running or stopped) within a
+          container spec.
+        examples: [0, 2]
 
   - id: k8s.replicaset
     prefix: k8s.replicaset

semantic_conventions/trace/rpc.yaml

@@ -2,7 +2,7 @@ groups:
   - id: rpc
     prefix: rpc
     brief: 'This document defines semantic conventions for remote procedure calls.'
-    events: [rpc.grpc.message]
+    events: [rpc.message]
     attributes:
       - id: system
         type: string
@@ -142,10 +142,10 @@ groups:
         note: >
           This is always required for jsonrpc. See the note in the general
           RPC conventions for more information.
-  - id: rpc.grpc.message
-    prefix: "message"  # TODO: Change the prefix to rpc.grpc.message?
+  - id: rpc.message
+    prefix: "message"  # TODO: Change the prefix to rpc.message?
     type: event
-    brief: "gRPC received/sent message."
+    brief: "RPC received/sent message."
     attributes:
       - id: type
         type:

spec-compliance-matrix.md

@@ -163,7 +163,7 @@ Note: Support for environment variables is optional.
 | In-memory (mock exporter)                                                      |          | +  | + | +  | +           | +    | +      | -   | -    | +   | +    | +     |
 | [OTLP](specification/protocol/otlp.md)                                         |          |    |   |    |             |      |        |     |      |     |      |       |
 | OTLP/gRPC Exporter                                                             | *        | +  | + | +  | +           |      | +      |     | +    | +   | +    | +     |
-| OTLP/HTTP binary Protobuf Exporter                                             | *        | +  | + | +  | +           | +    | +      |     |      | +   | -    | -     |
+| OTLP/HTTP binary Protobuf Exporter                                             | *        | +  | + | +  | +           | +    | +      |     | +    | +   | -    | -     |
 | OTLP/HTTP JSON Protobuf Exporter                                               |          | +  | - | +  | [-][py1003] |      | -      |     |      | +   | -    | -     |
 | OTLP/HTTP gzip Content-Encoding support                                        | X        | +  | + | +  | +           | +    | -      |     |      | -   | -    | -     |
 | Concurrent sending                                                             |          | -  | + | +  | [-][py1108] |      | -      |     | +    | -   | -    | -     |

specification/library-guidelines.md

@@ -132,5 +132,6 @@ guidelines on the performance expectations that API implementations should meet,
 Please refer to individual API specification for guidelines on what concurrency
 safeties should API implementations provide and how they should be documented:
 
-* [Metrics API](./metrics/api.md#concurrency)
+* [Metrics API](./metrics/api.md#concurrency-requirements)
+* [Metrics SDK](./metrics/sdk.md#concurrency-requirements)
 * [Tracing API](./trace/api.md#concurrency)

specification/metrics/api.md

@@ -32,6 +32,8 @@ Table of Contents
     * [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation)
     * [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations)
 * [Measurement](#measurement)
+* [Compatibility requirements](#compatibility-requirements)
+* [Concurrency requirements](#concurrency-requirements)
 
 </details>
 
@@ -408,7 +410,8 @@ function(s) independently.
 approach. Here are some examples:
 
 * Return a list (or tuple, generator, enumerator, etc.) of `Measurement`s.
-* Use an observer argument to allow individual `Measurement`s to be reported.
+* Use an observer result argument to allow individual `Measurement`s to be
+  reported.
 
 User code is recommended not to provide more than one `Measurement` with the
 same `attributes` in a single callback. If it happens, [OpenTelemetry
@@ -896,7 +899,8 @@ function(s) independently.
 approach. Here are some examples:
 
 * Return a list (or tuple, generator, enumerator, etc.) of `Measurement`s.
-* Use an observer argument to allow individual `Measurement`s to be reported.
+* Use an observer result argument to allow individual `Measurement`s to be
+  reported.
 
 User code is recommended not to provide more than one `Measurement` with the
 same `attributes` in a single callback. If it happens, the
@@ -978,15 +982,15 @@ for the interaction between the API and SDK.
 * A value
 * [`Attributes`](../common/common.md#attributes)
 
-## Compatibility
+## Compatibility requirements
 
 All the metrics components SHOULD allow new APIs to be added to existing
 components without introducing breaking changes.
 
 All the metrics APIs SHOULD allow optional parameter(s) to be added to existing
-APIs without introducing breaking changes.
+APIs without introducing breaking changes, if possible.
 
-## Concurrency
+## Concurrency requirements
 
 For languages which support concurrent execution the Metrics APIs provide
 specific guarantees and safeties.

specification/metrics/datamodel.md

@@ -386,6 +386,8 @@ Histograms consist of the following:
       (00:00:00 UTC on 1 January 1970).
   - A count (`count`) of the total population of points in the histogram.
   - A sum (`sum`) of all the values in the histogram.
+  - (optional) The min (`min`) of all values in the histogram.
+  - (optional) The max (`max`) of all values in the histogram.
   - (optional) A series of buckets with:
     - Explicit boundary values.  These values denote the lower and upper bounds
       for buckets and whether not a given observation would be recorded in this
@@ -398,6 +400,13 @@ denotes Delta temporality where accumulated event counts are reset to zero after
 and a new aggregation occurs. Cumulative, on the other hand, continues to
 aggregate events, resetting with the use of a new start time.
 
+The aggregation temporality also has implications on the min and max fields. Min
+and max are more useful for Delta temporality, since the values represented by
+Cumulative min and max will stabilize as more events are recorded. Additionally,
+it is possible to convert min and max from Delta to Cumulative, but not from
+Cumulative to Delta. When converting from Cumulative to Delta, min and max can
+be dropped, or captured in an alternative representation such as a gauge.
+
 Bucket counts are optional.  A Histogram without buckets conveys a
 population in terms of only the sum and count, and may be interpreted
 as a histogram with single bucket covering `(-Inf, +Inf)`.

specification/metrics/sdk.md

@@ -8,17 +8,19 @@ Table of Contents
 </summary>
 
 * [MeterProvider](#meterprovider)
-* [Attribute Limits](#attribute-limits)
+* [Attribute limits](#attribute-limits)
 * [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
   * [ExemplarReservoir](#exemplarreservoir)
-  * [Exemplar Defaults](#exemplar-defaults)
+  * [Exemplar defaults](#exemplar-defaults)
 * [MetricReader](#metricreader)
   * [Periodic exporting MetricReader](#periodic-exporting-metricreader)
 * [MetricExporter](#metricexporter)
   * [Push Metric Exporter](#push-metric-exporter)
   * [Pull Metric Exporter](#pull-metric-exporter)
-* [Defaults and Configuration](#defaults-and-configuration)
+* [Defaults and configuration](#defaults-and-configuration)
+* [Compatibility requirements](#compatibility-requirements)
+* [Concurrency requirements](#concurrency-requirements)
 
 </details>
 
@@ -393,7 +395,7 @@ This Aggregation informs the SDK to collect:
 - Count of `Measurement` values falling within explicit bucket boundaries.
 - Arithmetic sum of `Measurement` values in population.
 
-## Attribute Limits
+## Attribute limits
 
 Attributes which belong to Metrics are exempt from the
 [common rules of attribute limits](../common/common.md#attribute-limits) at this
@@ -477,7 +479,7 @@ from the original sample measurement.
 
 The `ExemplarReservoir` SHOULD avoid allocations when sampling exemplars.
 
-### Exemplar Defaults
+### Exemplar defaults
 
 The SDK will come with two types of built-in exemplar reservoirs:
 
@@ -574,6 +576,22 @@ SDK](../overview.md#sdk) authors MAY choose to add parameters (e.g. callback,
 filter, timeout). [OpenTelemetry SDK](../overview.md#sdk) authors MAY choose the
 return value type, or do not return anything.
 
+### Shutdown
+
+This method provides a way for the `MetricReader` to do any cleanup required.
+
+`Shutdown` MUST be called only once for each `MetricReader` instance. After the
+call to `Shutdown`, subsequent invocations to `Collect` are not allowed. SDKs
+SHOULD return some failure for these calls, if possible.
+
+`Shutdown` SHOULD provide a way to let the caller know whether it succeeded,
+failed or timed out.
+
+`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` CAN be
+implemented as a blocking API or an asynchronous API which notifies the caller
+via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors CAN
+decide if they want to make the shutdown timeout configurable.
+
 ### Periodic exporting MetricReader
 
 This is an implementation of the `MetricReader` which collects metrics based on
@@ -752,6 +770,32 @@ modeled to interact with other components in the SDK:
                                  +-----------------------------+
   ```
 
-## Defaults and Configuration
+## Defaults and configuration
+
+The SDK MUST provide configuration according to the [SDK environment
+variables](../sdk-environment-variables.md) specification.
+
+## Compatibility requirements
+
+All the metrics components SHOULD allow new methods to be added to existing
+components without introducing breaking changes.
+
+All the metrics SDK methods SHOULD allow optional parameter(s) to be added to
+existing methods without introducing breaking changes, if possible.
+
+## Concurrency requirements
+
+For languages which support concurrent execution the Metrics SDKs provide
+specific guarantees and safeties.
+
+**MeterProvider** - Meter creation, `ForceFlush` and `Shutdown` are safe to be
+called concurrently.
+
+**ExemplarFilter** - all methods are safe to be called concurrently.
+
+**ExemplarReservoir** - all methods are safe to be called concurrently.
+
+**MetricReader** - `Collect` and `Shutdown` are safe to be called concurrently.
 
-The SDK MUST provide configuration according to the [SDK environment variables](../sdk-environment-variables.md) specification.
+**MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called
+concurrently.

specification/metrics/semantic_conventions/http-metrics.md

@@ -17,18 +17,18 @@ type and units.
 
 Below is a table of HTTP server metric instruments.
 
-| Name                          | Instrument        | Units        | Description |
-|-------------------------------|-------------------|--------------|-------------|
-| `http.server.duration`        | ValueRecorder     | milliseconds | measures the duration of the inbound HTTP request |
-| `http.server.active_requests` | UpDownSumObserver | requests     | measures the number of concurrent HTTP requests that are currently in-flight |
+| Name                          | Instrument                 | Units        | Description |
+|-------------------------------|----------------------------|--------------|-------------|
+| `http.server.duration`        | Histogram                  | milliseconds | measures the duration of the inbound HTTP request |
+| `http.server.active_requests` | Asynchronous UpDownCounter | requests     | measures the number of concurrent HTTP requests that are currently in-flight |
 
 ### HTTP Client
 
 Below is a table of HTTP client metric instruments.
 
-| Name                   | Instrument    | Units        | Description |
-|------------------------|---------------|--------------|-------------|
-| `http.client.duration` | ValueRecorder | milliseconds | measure the duration of the outbound HTTP request |
+| Name                   | Instrument | Units        | Description |
+|------------------------|------------|--------------|-------------|
+| `http.client.duration` | Histogram  | milliseconds | measure the duration of the outbound HTTP request |
 
 ## Attributes