Rework FaaS semantic conventions. (#1781)
This commit is contained in:
Christian Neumüller
GitHub
parent
450410f7f6
commit
25f029b2e2
|
|
@ -8,32 +8,56 @@ groups:
|
|||
type: string
|
||||
required: always
|
||||
brief: >
|
||||
The name of the function being executed.
|
||||
The name of the single function that this runtime instance executes.
|
||||
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']
|
||||
- id: id
|
||||
type: string
|
||||
required: always
|
||||
brief: >
|
||||
The unique ID of the function
|
||||
being executed.
|
||||
note: >
|
||||
For example, in AWS Lambda this field corresponds to the
|
||||
[ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)
|
||||
value, in GCP to the URI of the resource, and in Azure to the
|
||||
[FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function)
|
||||
field.
|
||||
The unique ID of the single function that this runtime instance executes.
|
||||
note: |
|
||||
Depending on the cloud provider, use:
|
||||
|
||||
* **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.
|
||||
* **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.
|
||||
examples: ['arn:aws:lambda:us-west-2:123456789012:function:my-function']
|
||||
- id: version
|
||||
type: string
|
||||
brief: >
|
||||
The version string of the function being executed as defined in
|
||||
[Version Attributes](../../resource/semantic_conventions/README.md#version-attributes).
|
||||
examples: ['2.0.0']
|
||||
brief: The immutable version of the function being executed.
|
||||
note: |
|
||||
Depending on the cloud provider and platform, use:
|
||||
|
||||
* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html)
|
||||
(an integer represented as a decimal string).
|
||||
* **Google Cloud Run:** The [revision](https://cloud.google.com/run/docs/managing/revisions)
|
||||
(i.e., the function name plus the revision suffix).
|
||||
* **Google Cloud Functions:** The value of the
|
||||
[`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically).
|
||||
* **Azure Functions:** Not applicable. Do not set this attribute.
|
||||
examples: ['26', 'pinkfroid-00002']
|
||||
- id: instance
|
||||
type: string
|
||||
brief: >
|
||||
The execution environment ID as a string.
|
||||
examples: ['my-function:instance-0001']
|
||||
The execution environment ID as a string, that will be potentially reused
|
||||
for other invocations to the same function/function version.
|
||||
note: >
|
||||
* **AWS Lambda:** Use the (full) log stream name.
|
||||
examples: ['2021/06/28/[$LATEST]2f399eb14537447da05ab2a2e39309de']
|
||||
- id: max_memory
|
||||
type: int
|
||||
brief: >
|
||||
|
|
|
|||
|
|
@ -0,0 +1,13 @@
|
|||
groups:
|
||||
- id: aws.lambda
|
||||
prefix: aws.lambda
|
||||
brief: >
|
||||
Span attributes used by AWS Lambda (in addition to general `faas` attributes).
|
||||
attributes:
|
||||
- id: invoked_arn
|
||||
type: string
|
||||
brief: >
|
||||
The full invoked ARN as provided on the `Context` passed to the function
|
||||
(`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable).
|
||||
note: This may be different from `faas.id` if an alias is involved.
|
||||
examples: ['arn:aws:lambda:us-east-1:123456:function:myfunction:myalias']
|
||||
|
|
@ -4,20 +4,52 @@
|
|||
|
||||
**type:** `faas`
|
||||
|
||||
**Description:** A serverless instance.
|
||||
**Description:** A "function as a service" aka "serverless function" instance.
|
||||
|
||||
See also:
|
||||
|
||||
- The [Trace semantic conventions for FaaS](../../trace/semantic_conventions/faas.md)
|
||||
- The [Cloud resource conventions](cloud.md)
|
||||
|
||||
<!-- semconv faas_resource -->
|
||||
| Attribute | Type | Description | Examples | Required |
|
||||
|---|---|---|---|---|
|
||||
| `faas.name` | string | The name of the function being executed. | `my-function` | Yes |
|
||||
| `faas.id` | string | The unique ID of the function being executed. [1] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Yes |
|
||||
| `faas.version` | string | The version string of the function being executed as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `2.0.0` | No |
|
||||
| `faas.instance` | string | The execution environment ID as a string. | `my-function:instance-0001` | No |
|
||||
| `faas.max_memory` | int | The amount of memory available to the serverless function in MiB. [2] | `128` | No |
|
||||
| `faas.name` | string | The name of the single function that this runtime instance executes. [1] | `my-function` | 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]:** For example, in AWS Lambda this field corresponds to the [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) value, in GCP to the URI of the resource, and in Azure to the [FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function) field.
|
||||
**[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]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information.
|
||||
**[2]:** Depending on the cloud provider, use:
|
||||
|
||||
* **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.
|
||||
* **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.
|
||||
|
||||
**[3]:** Depending on the cloud provider and platform, use:
|
||||
|
||||
* **AWS Lambda:** The [function version](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html)
|
||||
(an integer represented as a decimal string).
|
||||
* **Google Cloud Run:** The [revision](https://cloud.google.com/run/docs/managing/revisions)
|
||||
(i.e., the function name plus the revision suffix).
|
||||
* **Google Cloud Functions:** The value of the
|
||||
[`K_REVISION` environment variable](https://cloud.google.com/functions/docs/env-var#runtime_environment_variables_set_automatically).
|
||||
* **Azure Functions:** Not applicable. Do not set this attribute.
|
||||
|
||||
**[4]:** * **AWS Lambda:** Use the (full) log stream name.
|
||||
|
||||
**[5]:** It's recommended to set this attribute since e.g. too little memory can easily stop a Java AWS Lambda function from working correctly. On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` provides this information.
|
||||
<!-- 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).
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@
|
|||
This document defines how to describe an instance of a function that runs without provisioning
|
||||
or managing of servers (also known as serverless functions or Function as a Service (FaaS)) with spans.
|
||||
|
||||
See also the [additional instructions for instrumenting AWS Lambda](instrumentation/aws-lambda.md).
|
||||
|
||||
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
|
||||
|
||||
<!-- toc -->
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
**Status**: [Experimental](../../../document-status.md)
|
||||
|
||||
This document defines how to apply semantic conventions when instrumenting an AWS Lambda request handler. AWS
|
||||
Lambda largely follows the conventions for [FaaS](../faas.md) while [HTTP](../http.md) conventions are also
|
||||
Lambda largely follows the conventions for [FaaS][faas] while [HTTP](../http.md) conventions are also
|
||||
applicable when handlers are for HTTP requests.
|
||||
|
||||
There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the
|
||||
|
|
@ -35,9 +35,30 @@ Lambda `Context`.
|
|||
|
||||
The following attributes SHOULD be set:
|
||||
|
||||
- [`faas.execution`](../faas.md) - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context`
|
||||
- [`faas.id`](../../../resource/semantic_conventions/faas.md) - The value of the invocation ARN for the function, which is always available through an accessor on the Lambda `Context`
|
||||
- [`cloud.account.id`](../../../resource/semantic_conventions/cloud.md) - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the value of `faas.id` as the fifth item when splitting on `:`
|
||||
- [`faas.execution`][faas] - The value of the AWS Request ID, which is always available through an accessor on the Lambda `Context`.
|
||||
- [`faas.id`][faasres] - The value of the invocation ARN
|
||||
for the function, which is always available through an accessor on the
|
||||
Lambda `Context`, modified as follows: Discard all parts beyond the seventh (when split on `:`;
|
||||
the seventh part is the function name) and append the [`faas.version`][faasres], separated by a colon.
|
||||
|
||||
Note that this is set as span attribute instead of resource attribute due to technical limitations
|
||||
(account ID is not available at startup).
|
||||
- [`cloud.account.id`][cloud] - In some languages, this is available as an accessor on the Lambda `Context`. Otherwise, it can be parsed from the value of `faas.id` as the fifth item when splitting on `:`
|
||||
|
||||
Also consider setting other attributes of the [`faas` resource][faasres] and [trace][faas] conventions
|
||||
and the [cloud resource conventions][cloud]. The following AWS Lambda-specific attribute MAY also be set:
|
||||
|
||||
<!-- semconv aws.lambda -->
|
||||
| Attribute | Type | Description | Examples | Required |
|
||||
|---|---|---|---|---|
|
||||
| `aws.lambda.invoked_arn` | string | The full invoked ARN as provided on the `Context` passed to the function (`Lambda-Runtime-Invoked-Function-Arn` header on the `/runtime/invocation/next` applicable). [1] | `arn:aws:lambda:us-east-1:123456:function:myfunction:myalias` | No |
|
||||
|
||||
**[1]:** This may be different from `faas.id` if an alias is involved.
|
||||
<!-- endsemconv -->
|
||||
|
||||
[faas]: ../faas.md (FaaS trace conventions)
|
||||
[faasres]: ../../../resource/semantic_conventions/faas.md (FaaS resource conventions)
|
||||
[cloud]: ../../../resource/semantic_conventions/cloud.md (Cloud resource conventions)
|
||||
|
||||
### Determining the parent of a span
|
||||
|
||||
|
|
@ -65,7 +86,7 @@ The Lambda span name and the [`http.route` span attribute](../http.md#http-serve
|
|||
be set to the [resource property][] from the proxy request event, which corresponds to the user configured HTTP
|
||||
route instead of the function name.
|
||||
|
||||
[`faas.trigger`](../faas.md) MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the
|
||||
[`faas.trigger`][faas] MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the
|
||||
available information in the proxy request event. `http.scheme` is available as the `x-forwarded-proto` header
|
||||
in the proxy request. Refer to the [input format][] for more details.
|
||||
|
||||
|
|
@ -95,7 +116,7 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O
|
|||
parsed from the value of the attribute using the [AWS X-Ray Propagator](../../../context/api-propagators.md) and
|
||||
added as a link to the span. This means the span may have as many links as messages in the batch.
|
||||
|
||||
- [`faas.trigger`](../faas.md) MUST be set to `pubsub`.
|
||||
- [`faas.trigger`][faas]] MUST be set to `pubsub`.
|
||||
- [`messaging.operation`](../messaging.md) MUST be set to `process`.
|
||||
- [`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`.
|
||||
- [`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`.
|
||||
|
|
@ -108,7 +129,7 @@ the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an O
|
|||
parsed from the value of the attribute using the [AWS X-Ray Propagator](../../../context/api-propagators.md) and
|
||||
added as a link to the span.
|
||||
|
||||
- [`faas.trigger`](../faas.md) MUST be set to `pubsub`.
|
||||
- [`faas.trigger`][faas] MUST be set to `pubsub`.
|
||||
- [`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`.
|
||||
- [`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`.
|
||||
- [`messaging.destination_kind`](../messaging.md#messaging-attributes) MUST be set to `queue`.
|
||||
|
|
@ -223,12 +244,12 @@ Span Lambda --> Span ProcBatch --> Span Proc1 (links to Span Prod1 and Span Prod
|
|||
|
||||
AWS Lambda resource information is available as [environment variables][] provided by the runtime.
|
||||
|
||||
- [`cloud.provider`](../../../resource/semantic_conventions/cloud.md) MUST be set to `aws`
|
||||
- [`cloud.region`](../../../resource/semantic_conventions/cloud.md) MUST be set to the value of the `AWS_REGION` environment variable
|
||||
- [`faas.name`](../../../resource/semantic_conventions/faas.md) MUST be set to the value of the `AWS_LAMBDA_FUNCTION_NAME` environment variable
|
||||
- [`faas.version`](../../../resource/semantic_conventions/faas.md) MUST be set to the value of the `AWS_LAMBDA_FUNCTION_VERSION` environment variable
|
||||
- [`cloud.provider`][cloud] MUST be set to `aws`
|
||||
- [`cloud.region`][cloud] MUST be set to the value of the `AWS_REGION` environment variable
|
||||
- [`faas.name`][faasres] MUST be set to the value of the `AWS_LAMBDA_FUNCTION_NAME` environment variable
|
||||
- [`faas.version`][faasres] MUST be set to the value of the `AWS_LAMBDA_FUNCTION_VERSION` environment variable
|
||||
|
||||
Note that [`faas.id`](../../../resource/semantic_conventions/faas.md) currently cannot be populated to resource
|
||||
Note that [`faas.id`][faasres] currently cannot be populated to resource
|
||||
because it is not available until function invocation.
|
||||
|
||||
[environment variables]: https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime
|
||||
|
|
|
|||
Loading…
Reference in New Issue