diff --git a/CHANGELOG.md b/CHANGELOG.md index a18e8cd1c27..bcd25624ba8 100644 --- 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 new file mode 100644 index 00000000000..e7eea9481d5 --- /dev/null +++ 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 index dc9bf701d77..3bc4413346f 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 (which must be multiplied by 1,048,576). + examples: 134217728 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..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.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..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 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). -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` |