Semantic conventions for FaaS spans

Status: Experimental

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.

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.

[1]: For the server/consumer span on the incoming side, faas.trigger MUST be set.

Clients invoking FaaS instances usually cannot set faas.trigger, since they would typically need to look in the payload to determine the event type. If clients set it, it should be the same as the trigger that corresponding incoming would have (i.e., this has nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP).

faas.trigger MUST be one of the following:

Function Name

There are 2 locations where the function’s name can be recorded: the span name and the faas.name Resource attribute.

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.

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. The faas.instance resource attribute 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.

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.

Incoming FaaS Span attributes

[1]: For the server/consumer span on the incoming side, faas.trigger MUST be set.

Clients invoking FaaS instances usually cannot set faas.trigger, since they would typically need to look in the payload to determine the event type. If clients set it, it should be the same as the trigger that corresponding incoming would have (i.e., this has nothing to do with the underlying transport used to make the API call to invoke the lambda, which is often HTTP).

Resource attributes as incoming FaaS span attributes

In addition to the attributes listed above, any FaaS or cloud resource attributes MAY instead be set as span attributes on incoming FaaS invocation spans: In some FaaS environments some of the information required for resource attributes is only readily available in the context of an invocation (e.g. as part of a “request context” argument) and while a separate API call to look up the resource information is often possible, it may be prohibitively expensive due to cold start duration concerns. The faas.id and cloud.account.id attributes on AWS are some examples. In principle, the above considerations apply to any resource attribute that fulfills the criteria above (not being readily available without some extra effort that could be expensive).

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.

[1]: SHOULD be equal to the faas.name resource attribute of the invoked function.

[2]: SHOULD be equal to the cloud.provider resource attribute of the invoked function.

[3]: SHOULD be equal to the cloud.region resource attribute of the invoked function.

[4]: 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.invoked_provider has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

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. FaaS instrumentations that produce faas spans with trigger datasource, SHOULD use the following set of attributes.

faas.document.operation has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

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.

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