From 3d409a7d4abe03e6b3df0c9c34e6086481b5a71a Mon Sep 17 00:00:00 2001 From: Alexandra Konrad <10500694+trisch-me@users.noreply.github.com> Date: Thu, 7 Mar 2024 18:04:52 +0100 Subject: [PATCH] move faas to registry (#525) Co-authored-by: Joao Grassi Co-authored-by: Josh Suereth --- docs/attributes-registry/README.md | 1 + docs/attributes-registry/faas.md | 93 ++++++++++++++ docs/faas/faas-metrics.md | 18 +-- docs/faas/faas-spans.md | 28 ++--- docs/resource/faas.md | 8 +- model/faas-common.yaml | 68 +--------- model/registry/faas.yaml | 195 +++++++++++++++++++++++++++++ model/resource/faas.yaml | 62 +-------- model/trace/faas.yaml | 84 +++---------- 9 files changed, 343 insertions(+), 214 deletions(-) create mode 100644 docs/attributes-registry/faas.md create mode 100644 model/registry/faas.yaml diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 113725054..00ff6ad8e 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -39,6 +39,7 @@ Currently, the following namespaces exist: * [Disk](disk.md) * [Error](error.md) * [Exception](exception.md) +* [FaaS](faas.md) * [Host](host.md) * [HTTP](http.md) * [K8s](k8s.md) diff --git a/docs/attributes-registry/faas.md b/docs/attributes-registry/faas.md new file mode 100644 index 000000000..4f8f5e4ea --- /dev/null +++ b/docs/attributes-registry/faas.md @@ -0,0 +1,93 @@ + + +# FaaS + +## FaaS Attributes + + +| Attribute | Type | Description | Examples | +|---|---|---|---| +| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | +| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | +| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | +| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | +| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | +| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | +| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [1] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | +| `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | +| `faas.invoked_name` | string | The name of the invoked function. [2] | `my-function` | +| `faas.invoked_provider` | string | The cloud provider of the invoked function. [3] | `alibaba_cloud` | +| `faas.invoked_region` | string | The cloud region of the invoked function. [4] | `eu-central-1` | +| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [5] | `134217728` | +| `faas.name` | string | The name of the single function that this runtime instance executes. [6] | `my-function`; `myazurefunctionapp/some-function-name` | +| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | +| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | +| `faas.version` | string | The immutable version of the function being executed. [7] | `26`; `pinkfroid-00002` | + +**[1]:** * **AWS Lambda:** Use the (full) log stream name. + +**[2]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. + +**[3]:** SHOULD be equal to the `cloud.provider` resource attribute of the invoked function. + +**[4]:** SHOULD be equal to the `cloud.region` resource attribute of the invoked function. + +**[5]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information (which must be multiplied by 1,048,576). + +**[6]:** This is the name of the function as configured/deployed on the FaaS +platform and is usually different from the name of the callback +function (which may be stored in the +[`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) +span attributes). + +For some cloud providers, the above definition is ambiguous. The following +definition of function name MUST be used for this attribute +(and consequently the span name) for the listed cloud providers/products: + +* **Azure:** The full name `/`, i.e., function app name + followed by a forward slash followed by the function name (this form + can also be seen in the resource JSON for the function). + This means that a span attribute MUST be used, as an Azure function + app can host multiple functions that would usually share + a TracerProvider (see also the `cloud.resource_id` attribute). + +**[7]:** Depending on the cloud provider and platform, use: + +* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). +* **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). +* **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). +* **Azure Functions:** Not applicable. Do not set this attribute. + +`faas.document.operation` 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 | +|---|---| +| `insert` | When a new object is created. | +| `edit` | When an object is modified. | +| `delete` | When an object is deleted. | + +`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 | + \ No newline at end of file diff --git a/docs/faas/faas-metrics.md b/docs/faas/faas-metrics.md index d6046b04f..22dbc9255 100644 --- a/docs/faas/faas-metrics.md +++ b/docs/faas/faas-metrics.md @@ -58,7 +58,7 @@ 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 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -88,7 +88,7 @@ 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 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -114,7 +114,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -140,7 +140,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -166,7 +166,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -192,7 +192,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -218,7 +218,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -248,7 +248,7 @@ 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 | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: @@ -274,7 +274,7 @@ This metric is [recommended][MetricRecommended]. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. | `datasource` | Recommended | `faas.trigger` MUST be one of the following: diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 34a03528d..ee38715df 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -42,8 +42,8 @@ If Spans following this convention are produced, a Resource of type `faas` MUST | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`cloud.resource_id`](../attributes-registry/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/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) [1] | `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 | -| `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [2] | `datasource` | Recommended | +| [`faas.invocation_id`](../attributes-registry/faas.md) | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [2] | `datasource` | Recommended | **[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. @@ -122,8 +122,8 @@ For incoming FaaS spans, the span kind MUST be `Server`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | Recommended | -| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Required | +| [`faas.coldstart`](../attributes-registry/faas.md) | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | Recommended | +| [`faas.trigger`](../attributes-registry/faas.md) | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Required | **[1]:** For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -161,9 +161,9 @@ 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 | -| `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.invoked_name`](../attributes-registry/faas.md) | string | The name of the invoked function. [1] | `my-function` | Required | +| [`faas.invoked_provider`](../attributes-registry/faas.md) | string | The cloud provider of the invoked function. [2] | `alibaba_cloud` | Required | +| [`faas.invoked_region`](../attributes-registry/faas.md) | string | The cloud region of the invoked function. [3] | `eu-central-1` | Conditionally Required: [4] | **[1]:** SHOULD be equal to the `faas.name` resource attribute of the invoked function. @@ -196,13 +196,13 @@ This section describes how to handle the span creation and additional attributes A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write. FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOULD use the following set of attributes. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.document.collection` | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Required | -| `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended | -| `faas.document.operation` | string | Describes the type of the operation that was performed on the data. | `insert` | Required | -| `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | +| [`faas.document.collection`](../attributes-registry/faas.md) | string | The name of the source on which the triggering operation was performed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | `myBucketName`; `myDbName` | Required | +| [`faas.document.name`](../attributes-registry/faas.md) | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | Recommended | +| [`faas.document.operation`](../attributes-registry/faas.md) | string | Describes the type of the operation that was performed on the data. | `insert` | Required | +| [`faas.document.time`](../attributes-registry/faas.md) | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | `faas.document.operation` 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. @@ -232,8 +232,8 @@ A function is scheduled to be executed regularly. The following additional attri | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.cron` | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended | -| `faas.time` | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | +| [`faas.cron`](../attributes-registry/faas.md) | string | A string containing the schedule period as [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). | `0/5 * * * ? *` | Recommended | +| [`faas.time`](../attributes-registry/faas.md) | string | A string containing the function invocation time in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Recommended | ### Other diff --git a/docs/resource/faas.md b/docs/resource/faas.md index c83eabc19..b354c2fda 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -17,10 +17,10 @@ See also: | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`cloud.resource_id`](../attributes-registry/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/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) [1] | `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 | -| `faas.instance` | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [2] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | -| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [3] | `134217728` | Recommended | -| `faas.name` | string | The name of the single function that this runtime instance executes. [4] | `my-function`; `myazurefunctionapp/some-function-name` | Required | -| `faas.version` | string | The immutable version of the function being executed. [5] | `26`; `pinkfroid-00002` | Recommended | +| [`faas.instance`](../attributes-registry/faas.md) | string | The execution environment ID as a string, that will be potentially reused for other invocations to the same function/function version. [2] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | +| [`faas.max_memory`](../attributes-registry/faas.md) | int | The amount of memory available to the serverless function converted to Bytes. [3] | `134217728` | Recommended | +| [`faas.name`](../attributes-registry/faas.md) | string | The name of the single function that this runtime instance executes. [4] | `my-function`; `myazurefunctionapp/some-function-name` | Required | +| [`faas.version`](../attributes-registry/faas.md) | string | The immutable version of the function being executed. [5] | `26`; `pinkfroid-00002` | Recommended | **[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. diff --git a/model/faas-common.yaml b/model/faas-common.yaml index 11a8b430c..9d951485b 100644 --- a/model/faas-common.yaml +++ b/model/faas-common.yaml @@ -4,66 +4,12 @@ groups: 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' - stability: experimental - - id: invoked_name - type: string - stability: experimental + - ref: faas.trigger + - ref: faas.invoked_name 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' - stability: experimental + - ref: faas.invoked_provider 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 - stability: experimental + - ref: faas.invoked_region requirement_level: conditionally_required: > For some cloud providers, like AWS or GCP, the region in which a @@ -73,9 +19,3 @@ groups: `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/registry/faas.yaml b/model/registry/faas.yaml new file mode 100644 index 000000000..12c5816a2 --- /dev/null +++ b/model/registry/faas.yaml @@ -0,0 +1,195 @@ +groups: + - id: registry.faas + brief: FaaS attributes + type: attribute_group + prefix: faas + attributes: + - id: name + type: string + stability: experimental + brief: > + The name of the single function that this runtime instance executes. + note: | + This is the name of the function as configured/deployed on the FaaS + platform and is usually different from the name of the callback + function (which may be stored in the + [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) + span attributes). + + For some cloud providers, the above definition is ambiguous. The following + definition of function name MUST be used for this attribute + (and consequently the span name) for the listed cloud providers/products: + + * **Azure:** The full name `/`, i.e., function app name + followed by a forward slash followed by the function name (this form + can also be seen in the resource JSON for the function). + This means that a span attribute MUST be used, as an Azure function + app can host multiple functions that would usually share + a TracerProvider (see also the `cloud.resource_id` attribute). + examples: ['my-function', 'myazurefunctionapp/some-function-name'] + - id: version + type: string + stability: experimental + brief: The immutable version of the function being executed. + note: | + Depending on the cloud provider and platform, use: + + * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) + (an integer represented as a decimal string). + * **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) + (i.e., the function name plus the revision suffix). + * **Google Cloud Functions:** The value of the + [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). + * **Azure Functions:** Not applicable. Do not set this attribute. + examples: ['26', 'pinkfroid-00002'] + - id: instance + type: string + stability: experimental + brief: > + The execution environment ID as a string, that will be potentially reused + for other invocations to the same function/function version. + note: > + * **AWS Lambda:** Use the (full) log stream name. + examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] + - id: max_memory + type: int + stability: experimental + brief: > + The amount of memory available to the serverless function converted to Bytes. + note: > + It's recommended to set this attribute since e.g. too little memory can easily + stop a Java AWS Lambda function from working correctly. + On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` + provides this information (which must be multiplied by 1,048,576). + examples: 134217728 + - id: trigger + stability: experimental + 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 + stability: experimental + 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 + stability: experimental + 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' + 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 + stability: experimental + 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' + - id: invocation_id + type: string + stability: experimental + brief: > + The invocation ID of the current function invocation. + examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' + - id: time + type: string + stability: experimental + brief: > + A string containing the function invocation time in the + [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) + format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). + examples: "2020-01-23T13:47:06Z" + - id: cron + type: string + stability: experimental + brief: > + A string containing the schedule period as + [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). + examples: "0/5 * * * ? *" + - id: coldstart + type: boolean + stability: experimental + brief: > + A boolean that is true if the serverless function is executed for the + first time (aka cold-start). + - id: document.collection + type: string + stability: experimental + brief: > + The name of the source on which the triggering operation was performed. + For example, in Cloud Storage or S3 corresponds to the bucket name, + and in Cosmos DB to the database name. + examples: ['myBucketName', 'myDbName'] + - id: document.operation + stability: experimental + type: + allow_custom_values: true + members: + - id: insert + value: 'insert' + brief: 'When a new object is created.' + - id: edit + value: 'edit' + brief: 'When an object is modified.' + - id: delete + value: 'delete' + brief: 'When an object is deleted.' + brief: 'Describes the type of the operation that was performed on the data.' + - id: document.time + type: string + stability: experimental + brief: > + A string containing the time when the data was accessed in the + [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) + format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). + examples: "2020-01-23T13:47:06Z" + - id: document.name + type: string + stability: experimental + brief: > + The document name/table subjected to the operation. + For example, in Cloud Storage or S3 is the name of + the file, and in Cosmos DB the table name. + examples: ["myFile.txt", "myTableName"] diff --git a/model/resource/faas.yaml b/model/resource/faas.yaml index e73ee3864..ab028c89b 100644 --- a/model/resource/faas.yaml +++ b/model/resource/faas.yaml @@ -5,63 +5,9 @@ groups: brief: > A serverless instance. attributes: - - id: name - type: string - stability: experimental + - ref: faas.name requirement_level: required - brief: > - The name of the single function that this runtime instance executes. - note: | - This is the name of the function as configured/deployed on the FaaS - platform and is usually different from the name of the callback - function (which may be stored in the - [`code.namespace`/`code.function`](/docs/general/attributes.md#source-code-attributes) - span attributes). - - For some cloud providers, the above definition is ambiguous. The following - definition of function name MUST be used for this attribute - (and consequently the span name) for the listed cloud providers/products: - - * **Azure:** The full name `/`, i.e., function app name - followed by a forward slash followed by the function name (this form - can also be seen in the resource JSON for the function). - This means that a span attribute MUST be used, as an Azure function - app can host multiple functions that would usually share - a TracerProvider (see also the `cloud.resource_id` attribute). - examples: ['my-function', 'myazurefunctionapp/some-function-name'] - - id: version - type: string - stability: experimental - brief: The immutable version of the function being executed. - note: | - Depending on the cloud provider and platform, use: - - * **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) - (an integer represented as a decimal string). - * **Google Cloud Run (Services):** The [revision](https://cloud.google.com/run/docs/managing/revisions) - (i.e., the function name plus the revision suffix). - * **Google Cloud Functions:** The value of the - [`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically). - * **Azure Functions:** Not applicable. Do not set this attribute. - examples: ['26', 'pinkfroid-00002'] - - id: instance - type: string - stability: experimental - brief: > - The execution environment ID as a string, that will be potentially reused - for other invocations to the same function/function version. - note: > - * **AWS Lambda:** Use the (full) log stream name. - examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de'] - - id: max_memory - type: int - stability: experimental - brief: > - The amount of memory available to the serverless function converted to Bytes. - note: > - It's recommended to set this attribute since e.g. too little memory can easily - stop a Java AWS Lambda function from working correctly. - On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` - provides this information (which must be multiplied by 1,048,576). - examples: 134217728 + - ref: faas.version + - ref: faas.instance + - ref: faas.max_memory - ref: cloud.resource_id diff --git a/model/trace/faas.yaml b/model/trace/faas.yaml index 3eb9b5335..58dba9d97 100644 --- a/model/trace/faas.yaml +++ b/model/trace/faas.yaml @@ -18,11 +18,7 @@ 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). - - id: invocation_id - type: string - stability: experimental - brief: 'The invocation ID of the current function invocation.' - examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' + - ref: faas.invocation_id - ref: cloud.resource_id - id: faas_span.datasource @@ -32,47 +28,12 @@ groups: Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. attributes: - - id: collection - type: string - stability: experimental + - ref: faas.document.collection requirement_level: required - brief: > - The name of the source on which the triggering operation was performed. - For example, in Cloud Storage or S3 corresponds to the bucket name, - and in Cosmos DB to the database name. - examples: ['myBucketName', 'myDbName'] - - id: operation - stability: experimental + - ref: faas.document.operation requirement_level: required - type: - allow_custom_values: true - members: - - id: insert - value: 'insert' - brief: 'When a new object is created.' - - id: edit - value: 'edit' - brief: 'When an object is modified.' - - id: delete - value: 'delete' - brief: 'When an object is deleted.' - brief: 'Describes the type of the operation that was performed on the data.' - - id: time - type: string - stability: experimental - brief: > - A string containing the time when the data was accessed in the - [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) - format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). - examples: "2020-01-23T13:47:06Z" - - id: name - type: string - stability: experimental - brief: > - The document name/table subjected to the operation. - For example, in Cloud Storage or S3 is the name of - the file, and in Cosmos DB the table name. - examples: ["myFile.txt", "myTableName"] + - ref: faas.document.time + - ref: faas.document.name - id: faas_span.http type: span @@ -96,21 +57,8 @@ groups: brief: > Semantic Convention for FaaS scheduled to be executed regularly. attributes: - - id: time - type: string - stability: experimental - brief: > - A string containing the function invocation time in the - [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) - format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). - examples: "2020-01-23T13:47:06Z" - - id: cron - type: string - stability: experimental - brief: > - A string containing the schedule period as - [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm). - examples: "0/5 * * * ? *" + - ref: faas.time + - ref: faas.cron - id: faas_span.in span_kind: server @@ -119,12 +67,7 @@ groups: brief: > Contains additional attributes for incoming FaaS spans. attributes: - - id: coldstart - type: boolean - stability: experimental - brief: > - A boolean that is true if the serverless function is executed for the - first time (aka cold-start). + - ref: faas.coldstart - ref: faas.trigger requirement_level: required note: | @@ -146,5 +89,16 @@ groups: Contains additional attributes for outgoing FaaS spans. attributes: - ref: faas.invoked_name + requirement_level: required - ref: faas.invoked_provider + requirement_level: required - ref: faas.invoked_region + 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.