Azure FaaS conventions. (#2502)
This commit is contained in:
Christian Neumüller
GitHub
parent
64e8e1c8fb
commit
7d2a40e537
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
**[2]:** Depending on the cloud provider, use:
|
||||
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.
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue