Allow all metric conventions to be either synchronous or asynchronous. (

#2458)
open-telemetry · Apr 8, 2022 · 7e35bec · 7e35bec
1 parent 0ddfacd
commit 7e35bec
Show file tree

Hide file tree

Showing 8 changed files with 140 additions and 124 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -121,6 +121,8 @@ release.
   ([#2290](https://github.com/open-telemetry/opentelemetry-specification/pull/2290))
 - Add semantic conventions for [CloudEvents](https://cloudevents.io).
   ([#1978](https://github.com/open-telemetry/opentelemetry-specification/pull/1978))
+- Allow all metric conventions to be either synchronous or asynchronous.
+  ([#2458](https://github.com/open-telemetry/opentelemetry-specification/pull/2458)
 - Add `process.cpu.utilization` metric.
   ([#2436](https://github.com/open-telemetry/opentelemetry-specification/pull/2436))
 - Add `rpc.system` value for Apache Dubbo.

diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md
@@ -13,6 +13,7 @@
 - [General Metric Semantic Conventions](#general-metric-semantic-conventions)
   * [Instrument Naming](#instrument-naming)
   * [Instrument Units](#instrument-units)
+  * [Instrument Types](#instrument-types)
 
 <!-- tocstop -->
 
@@ -165,3 +166,11 @@ total) are dimensionless and SHOULD use the default unit `1` (the unity).
 [annotations](https://ucum.org/ucum.html#para-curly) with curly braces to
 give additional meaning *without* the leading default unit (`1`). For example,
 use `{packets}`, `{errors}`, `{faults}`, etc.
+
+### Instrument Types
+
+The semantic metric conventions specification is written to use the names of the synchronous instrument types,
+like `Counter` or `UpDownCounter`. However, compliant implementations MAY use the asynchronous equivalent instead,
+like `Asynchronous Counter` or `Asynchronous UpDownCounter`.
+Whether implementations choose the synchronous type or the asynchronous equivalent is considered to be an
+implementation detail. Both choices are compliant with this specification.
diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md
@@ -32,33 +32,33 @@ type and units.
 
 Below is a table of FaaS invocation metric instruments.
 
-| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
-|------|------------|------|-------------------------------------------|-------------|
-| `faas.invoke_duration` | Histogram | milliseconds | `ms` | Measures the duration of the invocation |
-| `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start |
-| `faas.coldstarts` | Counter | default unit | `{coldstarts}` | Number of invocation cold starts. |
-| `faas.errors` | Counter | default unit | `{errors}` | Number of invocation errors. |
-| `faas.executions` | Counter | default unit | `{executions}` | Number of successful invocations. |
-| `faas.timeouts` | Counter | default unit | `{timeouts}` | Number of invocation timeouts. |
+| Name                   | Instrument Type ([*](README.md#instrument-types)) | Unit         | Unit ([UCUM](README.md#instrument-units)) | Description                                                                  |
+|------------------------|---------------------------------------------------|--------------|-------------------------------------------|------------------------------------------------------------------------------|
+| `faas.invoke_duration` | Histogram                                         | milliseconds | `ms`                                      | Measures the duration of the invocation                                      |
+| `faas.init_duration`   | Histogram                                         | milliseconds | `ms`                                      | Measures the duration of the function's initialization, such as a cold start |
+| `faas.coldstarts`      | Counter                                           | default unit | `{coldstarts}`                            | Number of invocation cold starts.                                            |
+| `faas.errors`          | Counter                                           | default unit | `{errors}`                                | Number of invocation errors.                                                 |
+| `faas.executions`      | Counter                                           | default unit | `{executions}`                            | Number of successful invocations.                                            |
+| `faas.timeouts`        | Counter                                           | default unit | `{timeouts}`                              | Number of invocation timeouts.                                               |
 
 Optionally, when applicable:
 
-| Name | Instrument | Unit | Unit ([UCUM](README.md#instrument-units)) | Description |
-|------|------------|------|-------------------------------------------|-------------|
-| `faas.mem_usage` | Histogram | Bytes | `By` | Distribution of max memory usage per invocation |
-| `faas.cpu_usage` | Histogram | milliseconds | `ms` | Distribution of cpu usage per invocation |
-| `faas.net_io` | Histogram | Bytes | `By` | Distribution of net I/O usage per invocation |
+| Name             | Instrument Type ([*](README.md#instrument-types)) | Unit         | Unit ([UCUM](README.md#instrument-units)) | Description                                     |
+|------------------|---------------------------------------------------|--------------|-------------------------------------------|-------------------------------------------------|
+| `faas.mem_usage` | Histogram                                         | Bytes        | `By`                                      | Distribution of max memory usage per invocation |
+| `faas.cpu_usage` | Histogram                                         | milliseconds | `ms`                                      | Distribution of cpu usage per invocation        |
+| `faas.net_io`    | Histogram                                         | Bytes        | `By`                                      | Distribution of net I/O usage per invocation    |
 
 ## Attributes
 
 Below is a table of the attributes to be included on FaaS metric events.
 
-| Name | Recommended | Notes and examples |
-|------|-------------|--------------------|
-| `faas.trigger` | Yes | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` |
-| `faas.invoked_name` | Yes | Name of the invoked function. Example: `my-function` |
-| `faas.invoked_provider` | Yes | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` |
-| `faas.invoked_region` | Yes | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` |
+| Name                    | Recommended | Notes and examples                                                                                                       |
+|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------|
+| `faas.trigger`          | Yes         | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` |
+| `faas.invoked_name`     | Yes         | Name of the invoked function. Example: `my-function`                                                                     |
+| `faas.invoked_provider` | Yes         | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws`                     |
+| `faas.invoked_region`   | Yes         | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1`                  |
 
 More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](../../trace/semantic_conventions/faas.md).
 For incoming FaaS executions, the function for which metrics are reported is already described by its [FaaS resource attributes](../../resource/semantic_conventions/faas.md).