semantic-conventions/specification/trace/semantic_conventions/faas.md

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
  • Difference between execution and instance
• Function Trigger Type
  • Datasource
  • HTTP
  • PubSub
  • Timer
  • Other

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
faas.coldstart	A boolean indicating that the serverless function is executed for the first time (aka cold start).	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.