Skip to content

Latest commit

 

History

History
90 lines (62 loc) · 5.49 KB

faas.md

File metadata and controls

90 lines (62 loc) · 5.49 KB
Raw

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.

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. For more information, refer to the Function Trigger Type section.

If Spans following this convention are produced, a Resource of type faas MUST exist following the Resource semantic convention.

Attribute name Notes and examples Required?
faas.trigger Type of the trigger on which the function is executed.
It SHOULD be one of the following strings: "datasource", "http", "pubsub", "timer", or "other".		 Yes
faas.execution String containing the execution id of the function. E.g. af9d5aa4-a685-4c5f-a22b-444f80b3cc28 No

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.

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

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

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.