Azure FaaS conventions. (#2502)

CHANGELOG.md

@@ -30,6 +30,10 @@ release.
 
 ### Semantic Conventions
 
+- Add details for FaaS conventions for Azure Functions and allow FaaS/Cloud
+  resources as span attributes on incoming FaaS spans
+  ([#2502](https://github.com/open-telemetry/opentelemetry-specification/pull/2502))
+
 ### Compatibility
 
 ### OpenTelemetry Protocol

semantic_conventions/resource/faas.yaml

@@ -9,32 +9,45 @@ groups:
         required: always
         brief: >
           The name of the single function that this runtime instance executes.
-        note:
+        note: |
           This is the name of the function as configured/deployed on the FaaS
           platform and is usually different from the name of the callback
           function (which may be stored in the
           [`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes)
           span attributes).
-        examples: ['my-function']
+
+          For some cloud providers, the above definition is ambiguous. The following
+          definition of function name MUST be used for this attribute
+          (and consequently the span name) for the listed cloud providers/products:
+
+          * **Azure:**  The full name `<FUNCAPP>/<FUNC>`, i.e., function app name
+            followed by a forward slash followed by the function name (this form
+            can also be seen in the resource JSON for the function).
+            This means that a span attribute MUST be used, as an Azure function
+            app can host multiple functions that would usually share
+            a TracerProvider (see also the `faas.id` attribute).
+        examples: ['my-function', 'myazurefunctionapp/some-function-name']
       - id: id
         type: string
         brief: >
           The unique ID of the single function that this runtime instance executes.
         note: |
-          Depending on the cloud provider, use:
+          On some cloud providers, it may not be possible to determine the full ID at startup,
+          so consider setting `faas.id` as a span attribute instead.
+
+          The exact value to use for `faas.id` depends on the cloud provider:
 
           * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
-          Take care not to use the "invoked ARN" directly but replace any
-          [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) with the resolved function version, as the same runtime instance may be invokable with multiple
-          different aliases.
+            Take care not to use the "invoked ARN" directly but replace any
+            [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html)
+            with the resolved function version, as the same runtime instance may be invokable with
+            multiple different aliases.
           * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names)
-          * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id).
-
-          On some providers, it may not be possible to determine the full ID at startup,
-          which is why this field cannot be made required. For example, on AWS the account ID
-          part of the ARN is not available without calling another AWS API
-          which may be deemed too slow for a short-running lambda function.
-          As an alternative, consider setting `faas.id` as a span attribute instead.
+          * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function,
+            *not* the function app, having the form
+            `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
+            This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
+            a TracerProvider.
         examples: ['arn:aws:lambda:us-west-2:123456789012:function:my-function']
       - id: version
         type: string

specification/resource/semantic_conventions/faas.md

@@ -11,31 +11,50 @@ See also:
 - The [Trace semantic conventions for FaaS](../../trace/semantic_conventions/faas.md)
 - The [Cloud resource conventions](cloud.md)
 
+## FaaS resource attributes
+
 <!-- semconv faas_resource -->
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
-| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function` | Yes |
+| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function`; `myazurefunctionapp/some-function-name` | Yes |
 | `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` | No |
 | `faas.version` | string | The immutable version of the function being executed. [3] | `26`; `pinkfroid-00002` | No |
 | `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` | No |
 | `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [5] | `128` | No |
 
-**[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 function (which may be stored in the [`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes) span attributes).
+**[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
+function (which may be stored in the
+[`code.namespace`/`code.function`](../../trace/semantic_conventions/span-general.md#source-code-attributes)
+span attributes).
+
+For some cloud providers, the above definition is ambiguous. The following
+definition of function name MUST be used for this attribute
+(and consequently the span name) for the listed cloud providers/products:
+
+* **Azure:**  The full name `<FUNCAPP>/<FUNC>`, i.e., function app name
+  followed by a forward slash followed by the function name (this form
+  can also be seen in the resource JSON for the function).
+  This means that a span attribute MUST be used, as an Azure function
+  app can host multiple functions that would usually share
+  a TracerProvider (see also the `faas.id` attribute).
+
+**[2]:** On some cloud providers, it may not be possible to determine the full ID at startup,
+so consider setting `faas.id` as a span attribute instead.
 
-**[2]:** Depending on the cloud provider, use:
+The exact value to use for `faas.id` depends on the cloud provider:
 
 * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
-Take care not to use the "invoked ARN" directly but replace any
-[alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) with the resolved function version, as the same runtime instance may be invokable with multiple
-different aliases.
+  Take care not to use the "invoked ARN" directly but replace any
+  [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html)
+  with the resolved function version, as the same runtime instance may be invokable with
+  multiple different aliases.
 * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names)
-* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id).
-
-On some providers, it may not be possible to determine the full ID at startup,
-which is why this field cannot be made required. For example, on AWS the account ID
-part of the ARN is not available without calling another AWS API
-which may be deemed too slow for a short-running lambda function.
-As an alternative, consider setting `faas.id` as a span attribute instead.
+* **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/en-us/rest/api/resources/resources/get-by-id) of the invoked function,
+  *not* the function app, having the form
+  `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>`.
+  This means that a span attribute MUST be used, as an Azure function app can host multiple functions that would usually share
+  a TracerProvider.
 
 **[3]:** Depending on the cloud provider and platform, use:
 
@@ -53,3 +72,9 @@ As an alternative, consider setting `faas.id` as a span attribute instead.
 <!-- 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).
+
+## Using span attributes instead of resource attributes
+
+There are cases where a FaaS resource attribute is better applied as a span
+attribute instead.
+See the [FaaS trace conventions](../../trace/semantic_conventions/faas.md) for more.

specification/trace/semantic_conventions/faas.md

@@ -15,6 +15,8 @@ See also the [additional instructions for instrumenting AWS Lambda](instrumentat
   * [Function Name](#function-name)
   * [Difference between execution and instance](#difference-between-execution-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)
 - [Outgoing Invocations](#outgoing-invocations)
 - [Function Trigger Type](#function-trigger-type)
   * [Datasource](#datasource)
@@ -76,7 +78,7 @@ weaker "SHOULD" requirement). Consumers that needs such guarantee can use
 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.
 Furthermore, FaaS providers encourage this behavior, e.g. [Google functions].
-This field MAY be set to help correlate function executions that belong to the same execution environment.
+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:
 
 - `faas.execution` refers to the current request ID handled by the function;
@@ -92,6 +94,8 @@ This section describes incoming FaaS invocations as they are reported by the Faa
 
 For incoming FaaS spans, the span kind MUST be `Server`.
 
+### Incoming FaaS Span attributes
+
 <!-- semconv faas_span.in -->
 | Attribute  | Type | Description  | Examples  | Required |
 |---|---|---|---|---|
@@ -109,6 +113,18 @@ nothing to do with the underlying transport used to make the API
 call to invoke the lambda, which is often HTTP).
 <!-- endsemconv -->
 
+### Resource attributes as incoming FaaS span attributes
+
+In addition to the attributes listed above, any [FaaS](../../resource/semantic_conventions/faas.md) or [cloud](../../resource/semantic_conventions/cloud.md) resource attributes MAY
+instead be set as span attributes on incoming FaaS invocation spans: In some
+FaaS environments some of the information required for resource
+attributes is only readily available in the context of an invocation (e.g. as part of a "request context" argument)
+and while a separate API call to look up the resource information is often possible, it
+may be prohibitively expensive due to cold start duration concerns.
+The `faas.id` and `cloud.account.id` attributes on AWS are some examples.
+In principle, the above considerations apply to any resource attribute that fulfills the criteria above
+(not being readily available without some extra effort that could be expensive).
+
 ## Outgoing Invocations
 
 This section describes outgoing FaaS invocations as they are reported by a client calling a FaaS instance.