open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
semantic-conventions/specification/trace/semantic_conventions/faas.md

168 lines
10 KiB
Markdown
Raw Blame History

# Semantic conventions for FaaS spans
This document defines how to describe an instance of a function that runs without provisioning or managing of servers (also known as serverless) with spans.
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc -->
- [General Attributes](#general-attributes)
* [Difference between execution and instance](#difference-between-execution-and-instance)
- [Incoming Invocations](#incoming-invocations)
- [Outgoing Invocations](#outgoing-invocations)
- [Function Trigger Type](#function-trigger-type)
* [Datasource](#datasource)
* [HTTP](#http)
* [PubSub](#pubsub)
* [Timer](#timer)
* [Other](#other)
- [Example](#example)
<!-- tocstop -->
## General Attributes
Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](http.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section.
If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../../resource/semantic_conventions/faas.md#function-as-a-service).
| Attribute name | Notes and examples | Required? |
|---|---|--|
| `faas.trigger` | Type of the trigger on which the function is executed. <br > It SHOULD be one of the following strings: "datasource", "http", "pubsub", "timer", or "other". | See below. |
| `faas.execution` | String containing the execution id of the function. E.g. `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | No |
On FaaS instances, `faas.trigger` MUST be set on incoming invocations.
Clients invoking FaaS instances MUST set `faas.trigger` on outgoing invocations, if it is known to the client.
This is, for example, *not* the case, when the transport layer is abstracted in a FaaS client framework without access to its configuration.
### Function Name
There are 2 locations where the function's name can be recorded: the span name and the
[`faas.name` Resource attribute](../../resource/semantic_conventions/faas.md#function-as-a-service).
It is guaranteed that if `faas.name` attribute is present it will contain the
function name, since it is defined in the semantic convention strictly for that
purpose. It is also highly likely that Span name will contain the function name
(e.g. for Span displaying purposes), but it is not guaranteed (since it is a
weaker "SHOULD" requirement). Consumers that needs such guarantee can use
`faas.name` attribute as the source. If `faas.name` is not present but other
`faas` attributes are present (indicating that the data is coming from a
function) then consumers may use the span name as the fallback source for the
function's name.
### Difference between execution and instance
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 span attribute `faas.execution` differs from the resource attribute `faas.instance` in the following:
- `faas.execution` refers to the current request ID handled by the function;
- `faas.instance` refers to the execution environment ID of the function.
[AWS lambda]: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html
[Azure functions]: https://docs.microsoft.com/en-us/azure/azure-functions/manage-connections#static-clients
[Google functions]: https://cloud.google.com/functions/docs/concepts/exec#function_scope_versus_global_scope
## Incoming Invocations
This section describes incoming FaaS invocations as they are reported by the FaaS instance itself.
For incoming FaaS spans, the span kind MUST be `Server`.
| Attribute | Type | Description | Required |
|---|---|---|---|
| `faas.coldstart` | boolean | Indicates that the serverless function is executed for the first time (aka cold start). | No |
## Outgoing Invocations
This section describes outgoing FaaS invocations as they are reported by a client calling a FaaS instance.
For outgoing FaaS spans, the span kind MUST be `Client`.
The values reported by the client for the attributes listed below SHOULD be equal to
the corresponding [FaaS resource attributes][] and [Cloud resource attributes][],
which the invoked FaaS instance reports about itself, if it's instrumented.
| Attribute | Corresponding resource attribute | Type | Description | Example | Required |
|---|---|---|---|---|---|
| `faas.invoked_name` | `faas.name` | string | The name of the invoked function. | `my-function` | Yes |
| `faas.invoked_provider` | `cloud.provider` | string | The cloud provider of the invoked function. | `aws` | Yes |
| `faas.invoked_region` | `cloud.region` | string | The cloud region of the invoked function. | `eu-central-1` | See below |
For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential
to uniquely identify the function and also part of its endpoint.
Since it's part of the endpoint being called, the region is always known to clients.
In these cases, `faas.invoked_region` MUST be set accordingly.
If the region is unknown to the client or not required for identifying the invoked function,
setting `faas.invoked_region` is optional.
[FaaS resource attributes]: ../../resource/semantic_conventions/faas.md
[Cloud resource attributes]: ../../resource/semantic_conventions/cloud.md
## Function Trigger Type
This section describes how to handle the span creation and additional attributes based on the value of the attribute `faas.trigger`.
### Datasource
A datasource function is triggered as a response to some data source operation such as a database or filesystem read/write.
For `faas` spans with trigger `datasource`, it is recommended to set the following attributes.
| Attribute name | Notes and examples | Required? |
|---|---|--|
| `faas.document.collection` | The name of the source on which the operation was perfomed. For example, in Cloud Storage or S3 corresponds to the bucket name, and in Cosmos DB to the database name. | Yes |
| `faas.document.operation` | Describes the type of the operation that was performed on the data.<br /> It SHOULD be one of the following strings: "insert", "edit", "delete". | Yes |
| `faas.document.time` | A string containing the time when the data was accessed in the [ISO 8601] format expressed in [UTC]. E.g. `"2020-01-23T13:47:06Z"` | Yes |
| `faas.document.name` | The document name/table subjected to the operation.<br /> For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | No |
### HTTP
The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](http.md#http-server-semantic-conventions).
### PubSub
A function is set to be executed when messages are sent to a messaging system.
In this case, multiple messages could be batch and forwarded at once to the same function execution.
Therefore, a different root span of type `faas` MUST be created for each message processed by the function, following the [Messaging systems semantic conventions](messaging.md).
This way, it is possible to correlate each individual message with its execution sender.
### Timer
A function is scheduled to be executed regularly. The following additional attributes are recommended.
| Attribute name | Notes and examples | Required? |
|---|---|--|
| `faas.time` | A string containing the function invocation time in the [ISO 8601] format expressed in [UTC]. E.g. `"2020-01-23T13:47:06Z"`| Yes |
| `faas.cron` | A string containing the schedule period as [Cron Expression]. E.g. `"0/5 * * * ? *"`| No |
[Cron Expression]: https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm
[ISO 8601]: https://www.iso.org/iso-8601-date-and-time-format.html
[UTC]: https://www.w3.org/TR/NOTE-datetime
### Other
Function as a Service offers such flexibility that it is not possible to fully cover with semantic conventions.
When a function does not satisfy any of the aforementioned cases, a span MUST set the attribute `faas.trigger` to `"other"`.
In this case, it is responsibility of the framework or instrumentation library to define the most appropriate attributes.
## Example
This example shows the FaaS attributes for a (non-FaaS) process hosted on Google Cloud Platform (Span A with kind `Client`), which invokes a Lambda function called "my-lambda-function" in Amazon Web Services (Span B with kind `Server`).
| Attribute Kind | Attribute | Span A (Client, GCP) | Span B (Server, AWS Lambda) |
| -------------- | ----------------------- | ---------------------- | -- |
| Resource | `cloud.provider` | `"gcp"` | `"aws"` |
| Resource | `cloud.region` | `"europe-west3"` | `"eu-central-1"` |
| Span | `faas.invoked_name` | `"my-lambda-function"` | n/a |
| Span | `faas.invoked_provider` | `"aws"` | n/a |
| Span | `faas.invoked_region` | `"eu-central-1"` | n/a |
| Span | `faas.trigger` | n/a | `"http"` |
| Span | `faas.execution` | n/a | `"af9d5aa4-a685-4c5f-a22b-444f80b3cc28"` |
| Span | `faas.coldstart` | n/a | `true` |
| Resource | `faas.name` | n/a | `"my-lambda-function"` |
| Resource | `faas.id` | n/a | `"arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function"` |
| Resource | `faas.version` | n/a | `"semver:2.0.0"` |
| Resource | `faas.instance` | n/a | `"my-lambda-function:instance-0001"` |
Reference in New Issue View Git Blame Copy Permalink