Azure FaaS conventions.

CHANGELOG.md

@@ -26,6 +26,9 @@ 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))
 - Update JVM metrics with JMX Gatherer values
   ([#2478](https://github.com/open-telemetry/opentelemetry-specification/pull/2478))
 

semantic_conventions/resource/faas.yaml

@@ -9,12 +9,17 @@ 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).
+
+          On Azure, an Azure function app can host multiple functions that would usually share
+          a TracerProvider, so this MUST be set as a span attribute instead on Azure. See also
+          `faas.id`. Additionally, the full name `<FUNCAPP>/<FUNC>` MUST be used for this attribute, i.e., function app name followed by a forward slash followed by the function
+          name (this form can also be seen in resource JSON for the function).
         examples: ['my-function']
       - id: id
         type: string
@@ -28,13 +33,13 @@ groups:
           [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).
+          * **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 (see also the paragraph below).
 
-          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.
+          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.
         examples: ['arn:aws:lambda:us-west-2:123456789012:function:my-function']
       - id: version
         type: string

specification/resource/semantic_conventions/faas.md

@@ -11,6 +11,8 @@ 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 |
 |---|---|---|---|---|
@@ -20,7 +22,16 @@ See also:
 | `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).
+
+On Azure, an Azure function app can host multiple functions that would usually share
+a TracerProvider, so this MUST be set as a span attribute instead on Azure. See also
+`faas.id`. Additionally, the full name `<FUNCAPP>/<FUNC>` MUST be used for this attribute, i.e., function app name followed by a forward slash followed by the function
+name (this form can also be seen in resource JSON for the function).
 
 **[2]:** Depending on the cloud provider, use:
 
@@ -29,13 +40,13 @@ 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).
+* **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 (see also the paragraph below).
 
-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.
+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.
 
 **[3]:** Depending on the cloud provider and platform, use:
 
@@ -53,3 +64,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 as part of a request context
+(a separate API call to look up the resource information is often possible but
+may be prohibitively expensive due to cold start duration concerns).
+The `faas.id` and `cloud.account.id` attributes on AWS in particular, are known
+for this, but the above considerations in principle apply to any resource
+attribute in FaaS environments.
+
 ## Outgoing Invocations
 
 This section describes outgoing FaaS invocations as they are reported by a client calling a FaaS instance.