# Semantic conventions for FaaS metrics
Site [llms.txt](/llms.txt)
---
**Status**: [Development][DocumentStatus]
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.
- [Metric instruments](#metric-instruments)
- [FaaS instance](#faas-instance)
- [Metric: `faas.invoke_duration`](#metric-faasinvoke_duration)
- [Metric: `faas.init_duration`](#metric-faasinit_duration)
- [Metric: `faas.coldstarts`](#metric-faascoldstarts)
- [Metric: `faas.errors`](#metric-faaserrors)
- [Metric: `faas.invocations`](#metric-faasinvocations)
- [Metric: `faas.timeouts`](#metric-faastimeouts)
- [Metric: `faas.mem_usage`](#metric-faasmem_usage)
- [Metric: `faas.cpu_usage`](#metric-faascpu_usage)
- [Metric: `faas.net_io`](#metric-faasnet_io)
- [References](#references)
- [Metric references](#metric-references)
> [!IMPORTANT]
> Existing FaaS instrumentations that are using
> [v1.44.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.44.0/docs/faas/faas-metrics.md)
> (or prior):
>
> * SHOULD NOT change the version of the FaaS conventions that they emit by
> default in their existing major version. Conventions include (but are not
> limited to) attributes, metric and span names, and unit of measure.
> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
> in their existing major version as a comma-separated list of category-specific values
> (e.g., `http`, `database`, `faas`). The list of values includes:
> * `faas` - emit the stable FaaS conventions, and stop emitting
> the experimental FaaS conventions that the instrumentation emitted
> previously.
> * `faas/dup` - emit both the experimental and stable FaaS conventions,
> allowing for a phased rollout of the stable semantic conventions.
> * The default behavior (in the absence of one of these values) is to continue
> emitting whatever version of the old experimental FaaS conventions
> the instrumentation was emitting previously.
> * Note: `faas/dup` has higher precedence than `faas` in case both values are present
> * SHOULD maintain (security patching at a minimum) their existing major version
> for at least six months after it starts emitting both sets of conventions.
> * MAY drop the environment variable in their next major version and emit only
> the stable FaaS conventions.
## Metric instruments
The following metric instruments describe FaaS operations.
### FaaS instance
The following metrics are recorded by the FaaS instance.
#### Metric: `faas.invoke_duration`
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with [`ExplicitBucketBoundaries` advisory parameter](/docs/specs/otel/metrics/api/#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.invoke_duration` | Histogram | `s` | Measures the duration of the function's logic execution. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.init_duration`
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with [`ExplicitBucketBoundaries` advisory parameter](/docs/specs/otel/metrics/api/#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.init_duration` | Histogram | `s` | Measures the duration of the function's initialization, such as a cold start. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.coldstarts`
This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.coldstarts` | Counter | `{coldstart}` | Number of invocation cold starts. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.errors`
This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.errors` | Counter | `{error}` | Number of invocation errors. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.invocations`
This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.invocations` | Counter | `{invocation}` | Number of successful invocations. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.timeouts`
This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.timeouts` | Counter | `{timeout}` | Number of invocation timeouts. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.mem_usage`
This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.mem_usage` | Histogram | `By` | Distribution of max memory usage per invocation. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.cpu_usage`
This metric is [recommended][MetricRecommended].
This metric SHOULD be specified with [`ExplicitBucketBoundaries` advisory parameter](/docs/specs/otel/metrics/api/#instrument-advisory-parameters) of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.cpu_usage` | Histogram | `s` | Distribution of CPU usage per invocation. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
#### Metric: `faas.net_io`
This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `faas.net_io` | Histogram | `By` | Distribution of net I/O usage per invocation. |  | |
**Attributes:**
| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`faas.trigger`](/docs/specs/semconv/registry/attributes/faas.md) |  | `Recommended` | string | Type of the trigger which caused this function invocation. | `datasource`; `http`; `pubsub` [(see more)](#faas-trigger-values) |
---
`faas.trigger` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
| --- | --- | --- |
| `datasource` | A response to some data source operation such as a database or filesystem read/write |  |
| `http` | To provide an answer to an inbound HTTP request |  |
| `other` | If none of the others apply |  |
| `pubsub` | A function is set to be executed when messages are sent to a messaging system |  |
| `timer` | A function is scheduled to be executed regularly |  |
## 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_c#gcp-cloudfunctions)
* [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/)
[DocumentStatus]: /docs/specs/otel/document-status/
[MetricRecommended]: /docs/specs/semconv/general/metric-requirement-level.md#recommended