diff --git a/CHANGELOG.md b/CHANGELOG.md index dac9f1f4422..0982dab594e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,6 +97,7 @@ 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 diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index ae6292135d6..322901d12ca 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -21,6 +21,7 @@ The following semantic conventions surrounding metrics are defined: * [System Metrics](system-metrics.md): Semantic conventions and instruments for standard system metrics. * [Process Metrics](process-metrics.md): Semantic conventions and instruments for standard process metrics. * [Runtime Environment Metrics](runtime-environment-metrics.md): Semantic conventions and instruments for runtime environment metrics. +* [FaaS Metrics](faas-metrics.md): Semantic conventions and instruments for FaaS metrics. Apart from semantic conventions for metrics and [traces](../../trace/semantic_conventions/README.md), OpenTelemetry also diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md new file mode 100644 index 00000000000..6fe734e0c5c --- /dev/null +++ b/specification/metrics/semantic_conventions/faas-metrics.md @@ -0,0 +1,77 @@ +# General + +**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 metrics. + +The conventions described in this section are FaaS (function as a service) specific. When FaaS operations occur, +metric events about those operations will be generated and reported to provide insights into the +operations. By adding FaaS attributes to metric events it allows for finely tuned filtering. + +**Disclaimer:** These are initial FaaS metric instruments and attributes but more may be added in the future. + + + + +- [Metric Instruments](#metric-instruments) + * [FaaS Invocations](#faas-invocations) +- [Attributes](#attributes) +- [References](#references) + * [Metric References](#metric-references) + + +## Metric Instruments + +The following metric instruments MUST be used to describe FaaS operations. They MUST be of the specified +type and units. + +### FaaS Invocations + +Below is a table of FaaS invocation metric instruments. + +| Name | Instrument | Units | Description | +|------|------------|----|-------------| +| `faas.invoke_duration` | Histogram | milliseconds | Measures the duration of the invocation | +| `faas.init_duration` | Histogram | milliseconds | Measures the duration of the function's initialization, such as a cold start | +| `faas.coldstarts` | Counter | default unit | Number of invocation cold starts. | +| `faas.errors` | Counter | default unit | Number of invocation errors. | +| `faas.executions` | Counter | default unit | Number of successful invocations. | +| `faas.timeouts` | Counter | default unit | Number of invocation timeouts. | + +Optionally, when applicable: + +| Name | Instrument | Units | Description | +|------|------------|----|-------------| +| `faas.mem_usage` | Histogram | bytes | Distribution of max memory usage per invocation | +| `faas.cpu_usage` | Histogram | milliseconds | Distribution of cpu usage per invocation | +| `faas.net_io` | Histogram | bytes | 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` | + +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). +Outgoing FaaS executions are identified using the `faas.invoked_*` attributes above. +`faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS execution events only. + +## References + +### Metric References + +Below are links to documentation regarding metrics that are available with different +FaaS providers. This list is not exhaustive. + +* [AWS Lambda Metrics](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-metrics.html) +* [AWS Lambda Insight Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Lambda-Insights-metrics.html) +* [Azure Functions Metrics](https://docs.microsoft.com/azure/azure-monitor/platform/metrics-supported) +* [Google CloudFunctions Metrics](https://cloud.google.com/monitoring/api/metrics_gcp#gcp-cloudfunctions) +* [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/)