From 3495731fbecf718f5441af51001621783561cf44 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 8 Feb 2023 11:45:31 -0500 Subject: [PATCH 1/6] Rename `faas.execution` to `faas.invocation_id` As decided in the FAAS SIG, the previous term was too generic. Also updated various documentation to better align with this terminology. --- semantic_conventions/trace/faas.yaml | 6 ++--- .../semantic_conventions/faas-metrics.md | 8 +++---- .../resource/semantic_conventions/faas.md | 2 +- .../trace/semantic_conventions/faas.md | 24 +++++++++---------- .../instrumentation/aws-lambda.md | 4 ++-- 5 files changed, 22 insertions(+), 22 deletions(-) diff --git a/semantic_conventions/trace/faas.yaml b/semantic_conventions/trace/faas.yaml index ff4963b164d..1faedb129fe 100644 --- a/semantic_conventions/trace/faas.yaml +++ b/semantic_conventions/trace/faas.yaml @@ -8,7 +8,7 @@ groups: serverless functions or Function as a Service (FaaS)) with spans. attributes: - id: trigger - brief: 'Type of the trigger which caused this function execution.' + brief: 'Type of the trigger which caused this function invocation.' note: | For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -37,9 +37,9 @@ groups: - id: other value: 'other' brief: 'If none of the others apply' - - id: execution + - id: invocation_id type: string - brief: 'The execution ID of the current function execution.' + brief: 'The invocation ID of the current function invocation.' examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' - id: faas_span.datasource diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md index e0e87059280..dd83c16f493 100644 --- a/specification/metrics/semantic_conventions/faas-metrics.md +++ b/specification/metrics/semantic_conventions/faas-metrics.md @@ -42,7 +42,7 @@ Below is a table of FaaS invocation metric instruments. | `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | | `faas.coldstarts` | Counter | default unit | `{coldstarts}` | Number of invocation cold starts. | | `faas.errors` | Counter | default unit | `{errors}` | Number of invocation errors. | -| `faas.executions` | Counter | default unit | `{executions}` | Number of successful invocations. | +| `faas.invocations` | Counter | default unit | `{invocations}` | Number of successful invocations. | | `faas.timeouts` | Counter | default unit | `{timeouts}` | Number of invocation timeouts. | Optionally, when applicable: @@ -65,9 +65,9 @@ Below is a table of the attributes to be included on FaaS metric events. | `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](../../trace/semantic_conventions/faas.md). -For incoming FaaS executions, the function for which metrics are reported is already described by its [FaaS resource attributes](../../resource/semantic_conventions/faas.md). -Outgoing FaaS executions are identified using the `faas.invoked_*` attributes above. -`faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS execution events only. +For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../../resource/semantic_conventions/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. ## References diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 6e58c5cadbd..bf80db83c9f 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -71,7 +71,7 @@ The exact value to use for `faas.id` depends on the cloud provider: **[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. -Note: The resource attribute `faas.instance` differs from the span attribute `faas.execution`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-execution-and-instance). +Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-invocation-and-instance). ## Using span attributes instead of resource attributes diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index 5434ce2d99e..c809ef1d16d 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -13,7 +13,7 @@ See also the [additional instructions for instrumenting AWS Lambda](instrumentat - [General Attributes](#general-attributes) * [Function Name](#function-name) - * [Difference between execution and instance](#difference-between-execution-and-instance) + * [Difference between invocation and instance](#difference-between-invocation-and-instance) - [Incoming Invocations](#incoming-invocations) * [Incoming FaaS Span attributes](#incoming-faas-span-attributes) * [Resource attributes as incoming FaaS span attributes](#resource-attributes-as-incoming-faas-span-attributes) @@ -37,8 +37,8 @@ If Spans following this convention are produced, a Resource of type `faas` MUST | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger which caused this function execution. [1] | `datasource` | Recommended | -| `faas.execution` | string | The execution ID of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | +| `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 | **[1]:** For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -73,15 +73,15 @@ purpose. It is also highly likely that Span name will contain the function name weaker "SHOULD" requirement). Consumers that needs such guarantee can use `faas.name` attribute as the source. -### Difference between execution and instance +### Difference between invocation and instance For performance reasons (e.g. [AWS lambda], or [Azure functions]), FaaS providers allocate an execution environment for a single instance of a function that is used to serve multiple requests. -Developers exploit this fact to solve the **cold start** issue, caching expensive resource computations between different function executions. +Developers exploit this fact to solve the **cold start** issue, caching expensive resource computations between different function invocations. Furthermore, FaaS providers encourage this behavior, e.g. [Google functions]. -The `faas.instance` resource attribute MAY be set to help correlate function executions that belong to the same execution environment. -The span attribute `faas.execution` differs from the [resource attribute][FaaS resource attributes] `faas.instance` in the following: +The `faas.instance` resource attribute MAY be set to help correlate function invocations that belong to the same execution environment. +The span attribute `faas.invocation_id` differs from the [resource attribute][FaaS resource attributes] `faas.instance` in the following: -- `faas.execution` refers to the current request ID handled by the function; +- `faas.invocation_id` refers to the ID of the current invocation of the function; - `faas.instance` refers to the execution environment ID of the function. [AWS lambda]: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html @@ -100,7 +100,7 @@ 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 execution. [1] | `datasource` | Required | +| `faas.trigger` | 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. @@ -197,9 +197,9 @@ The function responsibility is 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. -In this case, multiple messages could be batch and forwarded at once to the same function execution. +In this case, multiple messages could be batch and forwarded at once to the same function invocation. Therefore, a different root span of type `faas` MUST be created for each message processed by the function, following the [Messaging systems semantic conventions](messaging.md). -This way, it is possible to correlate each individual message with its execution sender. +This way, it is possible to correlate each individual message with its invocation sender. ### Timer @@ -230,7 +230,7 @@ This example shows the FaaS attributes for a (non-FaaS) process hosted on Google | Span | `faas.invoked_provider` | `"aws"` | n/a | | Span | `faas.invoked_region` | `"eu-central-1"` | n/a | | Span | `faas.trigger` | n/a | `"http"` | -| Span | `faas.execution` | n/a | `"af9d5aa4-a685-4c5f-a22b-444f80b3cc28"` | +| Span | `faas.invocation_id` | n/a | `"af9d5aa4-a685-4c5f-a22b-444f80b3cc28"` | | Span | `faas.coldstart` | n/a | `true` | | Resource | `faas.name` | n/a | `"my-lambda-function"` | | Resource | `faas.id` | n/a | `"arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"` | diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index cad57ad0eca..34a1362edf4 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -36,7 +36,7 @@ Lambda `Context`. The following attributes SHOULD be set: -- [`faas.execution`][faas] - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context`. +- [`faas.invocation_id`][faas] - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context`. - [`faas.id`][faasres] - The value of the invocation ARN for the function, which is always available through an accessor on the Lambda `Context`, modified as follows: Discard all parts beyond the seventh (when split on `:`; @@ -169,7 +169,7 @@ Function F: | Span Function | | Parent | | Span Client | | SpanKind | `CLIENT` | `SERVER` | | Status | `Ok` | `Ok` | -| `faas.execution` | | `79104EXAMPLEB723` | +| `faas.invocation_id` | | `79104EXAMPLEB723` | | `faas.id` | | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | | `faas.trigger` | | `http` | | `cloud.account.id` | | `12345678912` | From be356bb1664d745267c2c5d0d13d7459c1bf55a2 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 8 Feb 2023 11:57:06 -0500 Subject: [PATCH 2/6] Change `faas.max_memory` units to Bytes instead of MB For better unit consistency with other the semantic conventions. --- semantic_conventions/resource/faas.yaml | 6 +++--- specification/resource/semantic_conventions/faas.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index dc9bf701d77..3280a882510 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -75,10 +75,10 @@ groups: - id: max_memory type: int brief: > - The amount of memory available to the serverless function in MiB. + 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. - examples: 128 + provides this information (multiplied by 1000000). + examples: 128000000 diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index bf80db83c9f..e9f19fd0883 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -20,7 +20,7 @@ See also: | `faas.id` | string | The unique ID of the single function that this runtime instance executes. [2] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Recommended | | `faas.version` | string | The immutable version of the function being executed. [3] | `26`; `pinkfroid-00002` | 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. [4] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | -| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [5] | `128` | Recommended | +| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [5] | `128000000` | Recommended | **[1]:** This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback @@ -68,7 +68,7 @@ The exact value to use for `faas.id` depends on the cloud provider: **[4]:** * **AWS Lambda:** Use the (full) log stream name. -**[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. +**[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 (multiplied by 1000000). Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-invocation-and-instance). From 7785400b34d084146c3a519bfaf71da6a51b79d0 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Wed, 15 Feb 2023 17:13:33 -0500 Subject: [PATCH 3/6] Add migration schema (assuming this is released in the next minor version) --- schemas/1.19.0 | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 schemas/1.19.0 diff --git a/schemas/1.19.0 b/schemas/1.19.0 new file mode 100644 index 00000000000..2ac8ce75905 --- /dev/null +++ b/schemas/1.19.0 @@ -0,0 +1,67 @@ +file_format: 1.1.0 +schema_url: https://opentelemetry.io/schemas/1.18.0 +versions: + 1.19.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/3209 + - rename_attributes: + attribute_map: + faas.execution: faas.invocation_id + 1.18.0: + 1.17.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2957 + - rename_attributes: + attribute_map: + messaging.consumer_id: messaging.consumer.id + messaging.protocol: net.app.protocol.name + messaging.protocol_version: net.app.protocol.version + messaging.destination: messaging.destination.name + messaging.temp_destination: messaging.destination.temporary + messaging.destination_kind: messaging.destination.kind + messaging.message_id: messaging.message.id + messaging.conversation_id: messaging.message.conversation_id + messaging.message_payload_size_bytes: messaging.message.payload_size_bytes + messaging.message_payload_compressed_size_bytes: messaging.message.payload_compressed_size_bytes + messaging.rabbitmq.routing_key: messaging.rabbitmq.destination.routing_key + messaging.kafka.message_key: messaging.kafka.message.key + messaging.kafka.partition: messaging.kafka.destination.partition + messaging.kafka.tombstone: messaging.kafka.message.tombstone + messaging.rocketmq.message_type: messaging.rocketmq.message.type + messaging.rocketmq.message_tag: messaging.rocketmq.message.tag + messaging.rocketmq.message_keys: messaging.rocketmq.message.keys + messaging.kafka.consumer_group: messaging.kafka.consumer.group + 1.16.0: + 1.15.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2743 + - rename_attributes: + attribute_map: + http.retry_count: http.resend_count + 1.14.0: + 1.13.0: + spans: + changes: + # https://github.com/open-telemetry/opentelemetry-specification/pull/2614 + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr + 1.12.0: + 1.11.0: + 1.10.0: + 1.9.0: + 1.8.0: + spans: + changes: + - rename_attributes: + attribute_map: + db.cassandra.keyspace: db.name + db.hbase.namespace: db.name + 1.7.0: + 1.6.1: + 1.5.0: + 1.4.0: From 6b10fa6a184ed804672b2c2996e71623bdd3fe7c Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 15:20:36 -0500 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Anthony Mirabella --- semantic_conventions/resource/faas.yaml | 4 ++-- specification/metrics/semantic_conventions/faas-metrics.md | 2 +- specification/resource/semantic_conventions/faas.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 3280a882510..3bc4413346f 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/semantic_conventions/resource/faas.yaml @@ -80,5 +80,5 @@ groups: 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 (multiplied by 1000000). - examples: 128000000 + provides this information (which must be multiplied by 1,048,576). + examples: 134217728 diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md index dd83c16f493..72d2e48e18d 100644 --- a/specification/metrics/semantic_conventions/faas-metrics.md +++ b/specification/metrics/semantic_conventions/faas-metrics.md @@ -42,7 +42,7 @@ Below is a table of FaaS invocation metric instruments. | `faas.init_duration` | Histogram | milliseconds | `ms` | Measures the duration of the function's initialization, such as a cold start | | `faas.coldstarts` | Counter | default unit | `{coldstarts}` | Number of invocation cold starts. | | `faas.errors` | Counter | default unit | `{errors}` | Number of invocation errors. | -| `faas.invocations` | Counter | default unit | `{invocations}` | Number of successful invocations. | +| `faas.invocations` | Counter | default unit | `{invocations}` | Number of successful invocations. | | `faas.timeouts` | Counter | default unit | `{timeouts}` | Number of invocation timeouts. | Optionally, when applicable: diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index e9f19fd0883..c0556b8fcae 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -20,7 +20,7 @@ See also: | `faas.id` | string | The unique ID of the single function that this runtime instance executes. [2] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Recommended | | `faas.version` | string | The immutable version of the function being executed. [3] | `26`; `pinkfroid-00002` | 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. [4] | `2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de` | Recommended | -| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [5] | `128000000` | Recommended | +| `faas.max_memory` | int | The amount of memory available to the serverless function converted to Bytes. [5] | `134217728` | Recommended | **[1]:** This is the name of the function as configured/deployed on the FaaS platform and is usually different from the name of the callback @@ -68,7 +68,7 @@ The exact value to use for `faas.id` depends on the cloud provider: **[4]:** * **AWS Lambda:** Use the (full) log stream name. -**[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 (multiplied by 1000000). +**[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). Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-invocation-and-instance). From 032f30ad90ceb19aeb6b53228544b977e8373ba2 Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 15:23:52 -0500 Subject: [PATCH 5/6] Add changelog entries. --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a70e5f5c99..f35312d6c2b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,10 @@ release. - Move X-Ray Env Variable propagation to span link instead of parent for AWS Lambda. ([#3166](https://github.com/open-telemetry/opentelemetry-specification/pull/3166)) +- BREAKING: Rename faas.execution to faas.invocation_id + ([#3209](https://github.com/open-telemetry/opentelemetry-specification/pull/3209)) +- BREAKING: Change faas.max_memory units to Bytes instead of MB + ([#3209](https://github.com/open-telemetry/opentelemetry-specification/pull/3209)) ### Compatibility From 147e60aa5ce96d44428aaeef30562a18e37e46ab Mon Sep 17 00:00:00 2001 From: Tyler Benson Date: Thu, 16 Feb 2023 15:41:50 -0500 Subject: [PATCH 6/6] Fix schema_url --- schemas/1.19.0 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/1.19.0 b/schemas/1.19.0 index 2ac8ce75905..e7eea9481d5 100644 --- a/schemas/1.19.0 +++ b/schemas/1.19.0 @@ -1,5 +1,5 @@ file_format: 1.1.0 -schema_url: https://opentelemetry.io/schemas/1.18.0 +schema_url: https://opentelemetry.io/schemas/1.19.0 versions: 1.19.0: spans: