From aa6e3e5eb100a03e43413e5e272747b8784f8bcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Fri, 13 May 2022 21:01:20 +0200 Subject: [PATCH] Azure FaaS conventions. (#2502) --- CHANGELOG.md | 4 ++ semantic_conventions/resource/faas.yaml | 39 +++++++++----- .../resource/semantic_conventions/faas.md | 51 ++++++++++++++----- .../trace/semantic_conventions/faas.md | 18 ++++++- 4 files changed, 85 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd90f664ef8..ad01cc4580a 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/semantic_conventions/resource/faas.yaml b/semantic_conventions/resource/faas.yaml index 5fe8b230298..a610e7276ca 100644 --- a/semantic_conventions/resource/faas.yaml +++ b/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 `/`, 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//resourceGroups//providers/Microsoft.Web/sites//functions/`. + 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 diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index de019bc1dac..0450bdfc196 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/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 + | 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 `/`, 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//resourceGroups//providers/Microsoft.Web/sites//functions/`. + 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. 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. diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index 1740dcd7bea..f24495830e7 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/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 + | 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). +### 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.