Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rework FaaS semantic conventions. #1781

Merged
merged 8 commits into from
Jul 6, 2021
Merged

Rework FaaS semantic conventions. #1781

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0b8cbc7
Rework FaaS semantic conventions.
Oberon00 Jun 28, 2021
690be32
Add K_REVISON as GCF version.
Oberon00 Jun 29, 2021
b61d692
Fix markdownlint.
Oberon00 Jun 29, 2021
5e5dc94
Fill in PR#.
Oberon00 Jun 29, 2021
c108555
Typos.
Oberon00 Jun 29, 2021
5597a3f
Sync md
Oberon00 Jun 29, 2021
a04630e
Clarify faas.name.
Oberon00 Jun 29, 2021
8b426c1
Merge branch 'main' into rework-faas
Oberon00 Jul 6, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ release.

### Semantic Conventions

- Clean up FaaS semantic conventions, add `aws.lambda.invoked_arn`.
([#1781](https://github.com/open-telemetry/opentelemetry-specification/pull/1781))
- Remove `rpc.jsonrpc.method`, clarify that `rpc.method` should be used instead.
([#1748](https://github.com/open-telemetry/opentelemetry-specification/pull/1748))

Expand Down
56 changes: 40 additions & 16 deletions semantic_conventions/resource/faas.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,32 +8,56 @@ groups:
type: string
required: always
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know if this is possible?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The string replacement or that "the same runtime instance may be invokable with multiple different aliases"? Yes, I verified both. You can easily produce that scenario with the Lambda console UI by creating two different aliases for $LATEST and then you can test both and you will see that the logs end up in the same logstream without restart.

You can even test it without creating an extra alias. E.g. using aws lambda invoke --function-name 'arn:aws:lambda:us-east-1:12345:function:myfunction:$LATEST will end up with a different invoked ARN than just aws lambda invoke --function-name 'arn:aws:lambda:us-east-1:12345:function:myfunction, but the same invoked version & log stream.

[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: >
Expand Down
13 changes: 13 additions & 0 deletions semantic_conventions/trace/aws/lambda.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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']
48 changes: 40 additions & 8 deletions specification/resource/semantic_conventions/faas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]:** 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:

* **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.

**[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.
**[4]:** * **AWS Lambda:** Use the (full) log stream name.

**[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.
**[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).
2 changes: 2 additions & 0 deletions specification/trace/semantic_conventions/faas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down
45 changes: 33 additions & 12 deletions specification/trace/semantic_conventions/instrumentation/aws-lambda.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
carlosalberto marked this conversation as resolved.
Show resolved Hide resolved

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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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`.
Expand All @@ -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`.
Expand Down Expand Up @@ -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