Rename faas.execution to faas.invocation_id and change units for faas.max_memory (open-telemetry#3209)

tylerbenson · web-flow · commit 99d2fca8e05e · 2023-02-20T09:29:24.000-06:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -24,6 +24,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
 
diff --git a/schemas/1.19.0 b/schemas/1.19.0
@@ -0,0 +1,67 @@
+file_format: 1.1.0
+schema_url: https://opentelemetry.io/schemas/1.19.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:
diff --git 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 (which must be multiplied by 1,048,576).
+        examples: 134217728
diff --git 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
@@ -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
@@ -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] | `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,10 +68,10 @@ 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 (which must be multiplied by 1,048,576).
 <!-- endsemconv -->
 
-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
@@ -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
 <!-- semconv faas_span -->
 | 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
@@ -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` |
