Discourage faas.trigger for client/outgoing spans. (#1921)

* faas.trigger for client/outgoing.

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.

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

specification/trace/semantic_conventions/faas.md

@@ -35,10 +35,18 @@ If Spans following this convention are produced, a Resource of type `faas` MUST
 <!-- semconv faas_span -->
 | 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).
 <!-- endsemconv -->
 
 ## Outgoing Invocations