diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index 376ec3dc7d..5b87506fdb 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -20,7 +20,15 @@ operations. By adding FaaS attributes to metric events it allows for finely tune - [Metric Instruments](#metric-instruments) - * [FaaS Invocations](#faas-invocations) + * [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) - [Attributes](#attributes) - [References](#references) * [Metric References](#metric-references) @@ -29,43 +37,436 @@ operations. By adding FaaS attributes to metric events it allows for finely tune ## Metric Instruments -The following metric instruments MUST be used to describe FaaS operations. They MUST be of the specified -type and units. +The following metric instruments describe FaaS operations. -### FaaS Invocations +### Metric: `faas.invoke_duration` -Below is a table of FaaS invocation metric instruments. +This metric is [required][MetricRequired]. -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.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 | `{coldstart}` | Number of invocation cold starts. | -| `faas.errors` | Counter | default unit | `{error}` | Number of invocation errors. | -| `faas.invocations` | Counter | default unit | `{invocation}` | Number of successful invocations. | -| `faas.timeouts` | Counter | default unit | `{timeout}` | Number of invocation timeouts. | + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.invoke_duration` | Histogram | `ms` | Measures the duration of the invocation | + -Optionally, when applicable: + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | -| Name | Instrument Type ([*](/docs/general/metrics.md#instrument-types)) | Unit | Unit ([UCUM](/docs/general/metrics.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 | +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. -## Attributes +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.init_duration` + +This metric is [required][MetricRequired]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.init_duration` | Histogram | `ms` | Measures the duration of the function's initialization, such as a cold start | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.coldstarts` + +This metric is [required][MetricRequired]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.coldstarts` | Counter | `{coldstart}` | Number of invocation cold starts | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.errors` + +This metric is [required][MetricRequired]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.errors` | Counter | `{error}` | Number of invocation errors | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.invocations` + +This metric is [required][MetricRequired]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.invocations` | Counter | `{invocation}` | Number of successful invocations | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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. -Below is a table of the attributes to be included on FaaS metric events. +| Value | Description | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | -| Name | Requirement Level | Notes and examples | -|-------------------------|-------------------|--------------------------------------------------------------------------------------------------------------------------| -| `faas.trigger` | Required | Type of the trigger on which the function is invoked. SHOULD be one of: `datasource`, `http`, `pubsub`, `timer`, `other` | -| `faas.invoked_name` | Required | Name of the invoked function. Example: `my-function` | -| `faas.invoked_provider` | Required | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` | -| `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.timeouts` + +This metric is [required][MetricRequired]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.timeouts` | Counter | `{timeout}` | Number of invocation timeouts | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.mem_usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.mem_usage` | Histogram | `By` | Distribution of max memory usage per invocation | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.cpu_usage` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.cpu_usage` | Histogram | `ms` | Distribution of CPU usage per invocation | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + + +### Metric: `faas.net_io` + +This metric is [recommended][MetricRecommended]. + + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `faas.net_io` | Histogram | `By` | Distribution of net I/O usage per invocation | + + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| `faas.invoked_region` | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | + +**[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[2]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. + +`faas.invoked_provider` 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 | +|---|---| +| `alibaba_cloud` | Alibaba Cloud | +| `aws` | Amazon Web Services | +| `azure` | Microsoft Azure | +| `gcp` | Google Cloud Platform | +| `tencent_cloud` | Tencent Cloud | + +`faas.trigger` MUST be one of the following: + +| Value | Description | +|---|---| +| `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 | +| `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 | +| `other` | If none of the others apply | + +>>>>>>> 1cf9e98 (Generate FaaS metrics from YAML) + +## Attributes 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](faas-spans.md). -For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../resource/faas.md). +For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](/docs/resource/faas.md). Outgoing FaaS invocations 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 invocation events only. @@ -83,3 +484,5 @@ FaaS providers. This list is not exhaustive. * [OpenFaas Metrics](https://docs.openfaas.com/architecture/metrics/) [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md +[MetricRequired]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#required +[MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/metrics/metric-requirement-level.md#recommended diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 2a06a3c1ec..02b0911163 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -38,24 +38,13 @@ Span `name` should be set to the function name being executed. Depending on the If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../resource/faas.md). - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended | | `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | | [`cloud.resource_id`](../resource/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | -**[1]:** For the server/consumer span on the incoming side, -`faas.trigger` MUST be set. - -Clients invoking FaaS instances usually cannot set `faas.trigger`, -since they would typically need to look in the payload to determine -the event type. If clients set it, it should be the same as the -trigger that corresponding incoming would have (i.e., this has -nothing to do with the underlying transport used to make the API -call to invoke the lambda, which is often HTTP). - -**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup, +**[1]:** On some cloud providers, it may not be possible to determine the full ID at startup, so it may be necessary to set `cloud.resource_id` as a span attribute instead. The exact value to use for `cloud.resource_id` depends on the cloud provider. @@ -73,14 +62,24 @@ The following well-known definitions MUST be used if you set this attribute and This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share a TracerProvider. +**[2]:** For the server/consumer span on the incoming side, +`faas.trigger` MUST be set. + +Clients invoking FaaS instances usually cannot set `faas.trigger`, +since they would typically need to look in the payload to determine +the event type. If clients set it, it should be the same as the +trigger that corresponding incoming would have (i.e., this has +nothing to do with the underlying transport used to make the API +call to invoke the lambda, which is often HTTP). + `faas.trigger` MUST be one of the following: | Value | Description | |---|---| -| `datasource` | A response to some data source operation such as a database or filesystem read/write. | +| `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 | -| `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. | +| `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 | | `other` | If none of the others apply | @@ -158,7 +157,7 @@ The values reported by the client for the attributes listed below SHOULD be equa the corresponding [FaaS resource attributes][] and [Cloud resource attributes][], which the invoked FaaS instance reports about itself, if it's instrumented. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `faas.invoked_name` | string | The name of the invoked function. [1] | `my-function` | Required | diff --git a/model/faas-common.yaml b/model/faas-common.yaml new file mode 100644 index 0000000000..7f903bb57f --- /dev/null +++ b/model/faas-common.yaml @@ -0,0 +1,77 @@ +groups: + - id: attributes.faas.common + type: attribute_group + brief: "Describes FaaS attributes." + prefix: faas + attributes: + - id: trigger + brief: 'Type of the trigger which caused this function invocation.' + type: + allow_custom_values: false + members: + - id: datasource + value: 'datasource' + brief: 'A response to some data source operation such as a database or filesystem read/write' + - id: http + value: 'http' + brief: 'To provide an answer to an inbound HTTP request' + - id: pubsub + value: 'pubsub' + brief: 'A function is set to be executed when messages are sent to a messaging system' + - id: timer + value: 'timer' + brief: 'A function is scheduled to be executed regularly' + - id: other + value: 'other' + brief: 'If none of the others apply' + - id: invoked_name + type: string + requirement_level: required + brief: > + The name of the invoked function. + note: > + SHOULD be equal to the `faas.name` resource attribute of the + invoked function. + examples: 'my-function' + - id: invoked_provider + type: + allow_custom_values: true + members: + - id: 'alibaba_cloud' + value: 'alibaba_cloud' + brief: 'Alibaba Cloud' + - id: 'aws' + value: 'aws' + brief: 'Amazon Web Services' + - id: 'azure' + value: 'azure' + brief: 'Microsoft Azure' + - id: 'gcp' + value: 'gcp' + brief: 'Google Cloud Platform' + - id: 'tencent_cloud' + value: 'tencent_cloud' + brief: 'Tencent Cloud' + requirement_level: required + brief: > + The cloud provider of the invoked function. + note: > + SHOULD be equal to the `cloud.provider` resource attribute of the + invoked function. + - id: invoked_region + type: string + requirement_level: + conditionally_required: > + For some cloud providers, like AWS or GCP, the region in which a + function is hosted is essential to uniquely identify the function + and also part of its endpoint. Since it's part of the endpoint + being called, the region is always known to clients. In these cases, + `faas.invoked_region` MUST be set accordingly. If the region is + unknown to the client or not required for identifying the invoked + function, setting `faas.invoked_region` is optional. + brief: > + The cloud region of the invoked function. + note: > + SHOULD be equal to the `cloud.region` resource attribute of the + invoked function. + examples: 'eu-central-1' diff --git a/model/metrics/faas-metrics.yaml b/model/metrics/faas-metrics.yaml new file mode 100644 index 0000000000..823b145021 --- /dev/null +++ b/model/metrics/faas-metrics.yaml @@ -0,0 +1,108 @@ +groups: + - id: metric.faas.invoke_duration + type: metric + metric_name: faas.invoke_duration + brief: "Measures the duration of the invocation" + instrument: histogram + unit: "ms" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.init_duration + type: metric + metric_name: faas.init_duration + brief: "Measures the duration of the function's initialization, such as a cold start" + instrument: histogram + unit: "ms" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.coldstarts + type: metric + metric_name: faas.coldstarts + brief: "Number of invocation cold starts" + instrument: counter + unit: "{coldstart}" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.errors + type: metric + metric_name: faas.errors + brief: "Number of invocation errors" + instrument: counter + unit: "{error}" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.invocations + type: metric + metric_name: faas.invocations + brief: "Number of successful invocations" + instrument: counter + unit: "{invocation}" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.timeouts + type: metric + metric_name: faas.timeouts + brief: "Number of invocation timeouts" + instrument: counter + unit: "{timeout}" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.mem_usage + type: metric + metric_name: faas.mem_usage + brief: "Distribution of max memory usage per invocation" + instrument: histogram + unit: "By" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.cpu_usage + type: metric + metric_name: faas.cpu_usage + brief: "Distribution of CPU usage per invocation" + instrument: histogram + unit: "ms" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region + + - id: metric.faas.net_io + type: metric + metric_name: faas.net_io + brief: "Distribution of net I/O usage per invocation" + instrument: histogram + unit: "By" + attributes: + - ref: faas.trigger + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region diff --git a/model/trace/faas.yaml b/model/trace/faas.yaml index d30d41920a..84b7141b38 100644 --- a/model/trace/faas.yaml +++ b/model/trace/faas.yaml @@ -7,8 +7,7 @@ groups: runs without provisioning or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with spans. attributes: - - id: trigger - brief: 'Type of the trigger which caused this function invocation.' + - ref: faas.trigger note: | For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -19,33 +18,15 @@ groups: trigger that corresponding incoming would have (i.e., this has nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP). - type: - allow_custom_values: false - members: - - id: datasource - value: 'datasource' - brief: 'A response to some data source operation such as a database or filesystem read/write.' - - id: http - value: 'http' - brief: 'To provide an answer to an inbound HTTP request' - - id: pubsub - value: 'pubsub' - brief: 'A function is set to be executed when messages are sent to a messaging system.' - - id: timer - value: 'timer' - brief: 'A function is scheduled to be executed regularly.' - - id: other - value: 'other' - brief: 'If none of the others apply' - id: invocation_id type: string brief: 'The invocation ID of the current function invocation.' examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' - ref: cloud.resource_id + - id: faas_span.datasource prefix: faas.document type: span - extends: faas_span brief: > Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. @@ -90,24 +71,23 @@ groups: - id: faas_span.http type: span - extends: faas_span brief: > Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. constraints: - include: trace.http.server + attributes: [] - id: faas_span.pubsub type: span - extends: faas_span brief: > Semantic Convention for FaaS set to be executed when messages are sent to a messaging system. constraints: - include: messaging + attributes: [] - id: faas_span.timer - extends: faas_span prefix: faas type: span brief: > @@ -128,7 +108,6 @@ groups: examples: "0/5 * * * ? *" - id: faas_span.in - extends: faas_span span_kind: server prefix: faas type: span @@ -142,63 +121,24 @@ groups: first time (aka cold-start). - ref: faas.trigger requirement_level: required + note: | + For the server/consumer span on the incoming side, + `faas.trigger` MUST be set. + + Clients invoking FaaS instances usually cannot set `faas.trigger`, + since they would typically need to look in the payload to determine + the event type. If clients set it, it should be the same as the + trigger that corresponding incoming would have (i.e., this has + nothing to do with the underlying transport used to make the API + call to invoke the lambda, which is often HTTP). - id: faas_span.out - extends: faas_span span_kind: client prefix: faas type: span brief: > Contains additional attributes for outgoing FaaS spans. attributes: - - id: invoked_name - type: string - requirement_level: required - brief: > - The name of the invoked function. - note: > - SHOULD be equal to the `faas.name` resource attribute of the - invoked function. - examples: 'my-function' - - id: invoked_provider - type: - allow_custom_values: true - members: - - id: 'alibaba_cloud' - value: 'alibaba_cloud' - brief: 'Alibaba Cloud' - - id: 'aws' - value: 'aws' - brief: 'Amazon Web Services' - - id: 'azure' - value: 'azure' - brief: 'Microsoft Azure' - - id: 'gcp' - value: 'gcp' - brief: 'Google Cloud Platform' - - id: 'tencent_cloud' - value: 'tencent_cloud' - brief: 'Tencent Cloud' - requirement_level: required - brief: > - The cloud provider of the invoked function. - note: > - SHOULD be equal to the `cloud.provider` resource attribute of the - invoked function. - - id: invoked_region - type: string - requirement_level: - conditionally_required: > - For some cloud providers, like AWS or GCP, the region in which a - function is hosted is essential to uniquely identify the function - and also part of its endpoint. Since it's part of the endpoint - being called, the region is always known to clients. In these cases, - `faas.invoked_region` MUST be set accordingly. If the region is - unknown to the client or not required for identifying the invoked - function, setting `faas.invoked_region` is optional. - brief: > - The cloud region of the invoked function. - note: > - SHOULD be equal to the `cloud.region` resource attribute of the - invoked function. - examples: 'eu-central-1' + - ref: faas.invoked_name + - ref: faas.invoked_provider + - ref: faas.invoked_region