diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e0720246bc..100e01c6255 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -106,6 +106,8 @@ release. ([#1810](https://github.com/open-telemetry/opentelemetry-specification/pull/1810)) - Clarifications for `http.client_ip` and `http.host`. ([#1890](https://github.com/open-telemetry/opentelemetry-specification/pull/1890)) +- Change meaning and discourage use of `faas.trigger` for FaaS clients (outgoing). + ([#1921](https://github.com/open-telemetry/opentelemetry-specification/pull/1921)) - Add HTTP request and response headers semantic conventions. ([#1898](https://github.com/open-telemetry/opentelemetry-specification/pull/1898)) - Add `k8s.container.restart_count` Resource attribute. diff --git a/semantic_conventions/trace/faas.yaml b/semantic_conventions/trace/faas.yaml index ddc0e259cc6..d451d9273b4 100644 --- a/semantic_conventions/trace/faas.yaml +++ b/semantic_conventions/trace/faas.yaml @@ -7,14 +7,17 @@ groups: serverless functions or Function as a Service (FaaS)) with spans. attributes: - id: trigger - required: - conditional: > - On FaaS instances, faas.trigger MUST be set on incoming invocations. - Clients invoking FaaS instances MUST set `faas.trigger` on outgoing - invocations, if it is known to the client. This is, for example, not - the case, when the transport layer is abstracted in a FaaS client - framework without access to its configuration. - brief: 'Type of the trigger on which the function is executed.' + brief: 'Type of the trigger which caused this function execution.' + note: | + For the server/consumer span on the incoming side, + `faas.trigger` MUST be set. + + Clients invoking FaaS instances usually cannot set `faas.trigger`, + since they would typically need to look in the payload to determine + the event type. If clients set it, it should be the same as the + trigger that corresponding incoming would have (i.e., this has + nothing to do with the underlying transport used to make the API + call to invoke the lambda, which is often HTTP). type: allow_custom_values: false members: @@ -133,6 +136,8 @@ groups: brief: > A boolean that is true if the serverless function is executed for the first time (aka cold-start). + - ref: faas.trigger + required: always - id: faas_span.out extends: faas_span diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index 4b0a2287286..f5eb29b3280 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -35,10 +35,18 @@ If Spans following this convention are produced, a Resource of type `faas` MUST | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| `faas.trigger` | string | Type of the trigger on which the function is executed. | `datasource` | Conditional [1] | +| `faas.trigger` | string | Type of the trigger which caused this function execution. [1] | `datasource` | No | | `faas.execution` | string | The execution ID of the current function execution. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | No | -**[1]:** On FaaS instances, faas.trigger MUST be set on incoming invocations. Clients invoking FaaS instances MUST set `faas.trigger` on outgoing invocations, if it is known to the client. This is, for example, not the case, when the transport layer is abstracted in a FaaS client framework without access to its configuration. +**[1]:** For the server/consumer span on the incoming side, +`faas.trigger` MUST be set. + +Clients invoking FaaS instances usually cannot set `faas.trigger`, +since they would typically need to look in the payload to determine +the event type. If clients set it, it should be the same as the +trigger that corresponding incoming would have (i.e., this has +nothing to do with the underlying transport used to make the API +call to invoke the lambda, which is often HTTP). `faas.trigger` MUST be one of the following: @@ -88,6 +96,17 @@ For incoming FaaS spans, the span kind MUST be `Server`. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| | `faas.coldstart` | boolean | A boolean that is true if the serverless function is executed for the first time (aka cold-start). | | No | +| `faas.trigger` | string | Type of the trigger which caused this function execution. [1] | `datasource` | Yes | + +**[1]:** For the server/consumer span on the incoming side, +`faas.trigger` MUST be set. + +Clients invoking FaaS instances usually cannot set `faas.trigger`, +since they would typically need to look in the payload to determine +the event type. If clients set it, it should be the same as the +trigger that corresponding incoming would have (i.e., this has +nothing to do with the underlying transport used to make the API +call to invoke the lambda, which is often HTTP). ## Outgoing Invocations