diff --git a/specification/README.md b/specification/README.md index cba083b25e..e5dbedb35c 100644 --- a/specification/README.md +++ b/specification/README.md @@ -8,6 +8,7 @@ Semantic Conventions are defined for the following areas: * [General](general/README.md): General Semantic Conventions. * [Exceptions](exceptions/README.md): Semantic Conventions for Exceptions. +* [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. * [Database](database/README.md): Semantic Conventions for database operations. diff --git a/specification/faas/README.md b/specification/faas/README.md new file mode 100644 index 0000000000..f25eb48a9c --- /dev/null +++ b/specification/faas/README.md @@ -0,0 +1,16 @@ +# Semantic conventions for FaaS + +**Status**: [Experimental][DocumentStatus] + +This document defines semantic conventions for Function as a Service (FaaS) spans, metrics and logs. + +Semantic conventions for FaaS are defined for the following signals: + +* [FaaS Spans](faas-spans.md): Semantic Conventions for FaaS *spans*. +* [FaaS Metrics](faas-metrics.md): Semantic Conventions for FaaS *metrics*. + +Technology specific semantic conventions are defined for the following FaaS services: + +* [AWS Lambda](aws-lambda.md): Semantic Conventions for *AWS Lambda*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/faas/aws-lambda.md similarity index 91% rename from specification/trace/semantic_conventions/instrumentation/aws-lambda.md rename to specification/faas/aws-lambda.md index 3d3611b2c3..08285e3e50 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/faas/aws-lambda.md @@ -9,7 +9,7 @@ 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 use cases. - + @@ -50,9 +50,9 @@ and the [cloud resource conventions][cloud]. The following AWS Lambda-specific a **[1]:** This may be different from `cloud.resource_id` if an alias is involved. -[faas]: ../faas.md (FaaS trace conventions) -[faasres]: ../../../resource/semantic_conventions/faas.md (FaaS resource conventions) -[cloud]: ../../../resource/semantic_conventions/cloud.md (Cloud resource conventions) +[faas]: faas-spans.md (FaaS trace conventions) +[faasres]: /specification/resource/semantic_conventions/faas.md (FaaS resource conventions) +[cloud]: /specification/resource/semantic_conventions/cloud.md (Cloud resource conventions) ### AWS X-Ray Environment Span Link @@ -111,12 +111,12 @@ For every message in the event, the [message system attributes][] (not message a the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/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. -See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. +See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`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` or `messaging.source.kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. +- [`messaging.operation`](/specification/trace/semantic_conventions/messaging.md) MUST be set to `process`. +- [`messaging.system`](/specification/trace/semantic_conventions/messaging.md) MUST be set to `AmazonSQS`. +- [`messaging.destination.kind` or `messaging.source.kind`](/specification/trace/semantic_conventions/messaging.md#messaging-attributes) MUST be set to `queue`. ### SQS Message @@ -125,13 +125,13 @@ corresponding to the SQS event. The [message system attributes][] (not message a the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/context/api-propagators.md) and added as a link to the span. -See [compatibility](../../../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. +See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info. - [`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.operation`](/specification/trace/semantic_conventions/messaging.md#messaging-attributes) MUST be set to `process`. +- [`messaging.system`](/specification/trace/semantic_conventions/messaging.md#messaging-attributes) MUST be set to `AmazonSQS`. -Other [Messaging attributes](../messaging.md#messaging-attributes) SHOULD be set based on the available information in the SQS message +Other [Messaging attributes](/specification/trace/semantic_conventions/messaging.md#messaging-attributes) SHOULD be set based on the available information in the SQS message event. Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` in instrumentation for SQS diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/faas/faas-metrics.md similarity index 98% rename from specification/metrics/semantic_conventions/faas-metrics.md rename to specification/faas/faas-metrics.md index 703b727de6..631be8236c 100644 --- a/specification/metrics/semantic_conventions/faas-metrics.md +++ b/specification/faas/faas-metrics.md @@ -64,8 +64,8 @@ Below is a table of the attributes to be included on FaaS metric events. | `faas.invoked_provider` | Required | Cloud provider of the invoked function. Corresponds to the resource `cloud.provider`. Example: `aws` | | `faas.invoked_region` | Required | Cloud provider region of invoked function. Corresponds to resource `cloud.region`. Example: `us-east-1` | -More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](../../trace/semantic_conventions/faas.md). -For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../../resource/semantic_conventions/faas.md). +More details on these attributes, the function name and the difference compared to the faas.invoked_name can be found at the related [FaaS tracing specification](faas-spans.md). +For incoming FaaS invocations, the function for which metrics are reported is already described by its [FaaS resource attributes](../resource/semantic_conventions/faas.md). Outgoing FaaS invocations are identified using the `faas.invoked_*` attributes above. `faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS invocation events only. diff --git a/specification/trace/semantic_conventions/faas.md b/specification/faas/faas-spans.md similarity index 91% rename from specification/trace/semantic_conventions/faas.md rename to specification/faas/faas-spans.md index ad358e6b76..a75837d02e 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/faas/faas-spans.md @@ -5,7 +5,7 @@ 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). +See also the [additional instructions for instrumenting AWS Lambda](aws-lambda.md). @@ -32,14 +32,14 @@ See also the [additional instructions for instrumenting AWS Lambda](instrumentat 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](/specification/http/http-spans.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). +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 | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended | | `faas.invocation_id` | string | The invocation ID of the current function invocation. | `af9d5aa4-a685-4c5f-a22b-444f80b3cc28` | Recommended | -| [`cloud.resource_id`](../../resource/semantic_conventions/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | +| [`cloud.resource_id`](../resource/semantic_conventions/cloud.md) | string | Cloud provider-specific native identifier of the monitored cloud resource (e.g. an [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) on AWS, a [fully qualified resource ID](https://learn.microsoft.com/en-us/rest/api/resources/resources/get-by-id) on Azure, a [full resource name](https://cloud.google.com/apis/design/resource_names#full_resource_name) on GCP) [2] | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions//resourceGroups//providers/Microsoft.Web/sites//functions/` | Recommended | **[1]:** For the server/consumer span on the incoming side, `faas.trigger` MUST be set. @@ -83,7 +83,7 @@ The following well-known definitions MUST be used if you set this attribute and ### 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). +[`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 @@ -134,7 +134,7 @@ 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](../../resource/semantic_conventions/faas.md) or [cloud](../../resource/semantic_conventions/cloud.md) resource attributes MAY +In addition to the attributes listed above, any [FaaS](../resource/semantic_conventions/faas.md) or [cloud](../resource/semantic_conventions/cloud.md) 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) @@ -180,8 +180,8 @@ which the invoked FaaS instance reports about itself, if it's instrumented. | `tencent_cloud` | Tencent Cloud | -[FaaS resource attributes]: ../../resource/semantic_conventions/faas.md -[Cloud resource attributes]: ../../resource/semantic_conventions/cloud.md +[FaaS resource attributes]: ../resource/semantic_conventions/faas.md +[Cloud resource attributes]: ../resource/semantic_conventions/cloud.md ## Function Trigger Type @@ -217,7 +217,7 @@ The function responsibility is to provide an answer to an inbound HTTP request. 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 invocation. -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). +Therefore, a different root span of type `faas` MUST be created for each message processed by the function, following the [Messaging systems semantic conventions](/specification/trace/semantic_conventions/messaging.md). This way, it is possible to correlate each individual message with its invocation sender. ### Timer diff --git a/specification/general/metrics-general.md b/specification/general/metrics-general.md index 0c3ac8f2cc..e028e29eed 100644 --- a/specification/general/metrics-general.md +++ b/specification/general/metrics-general.md @@ -22,7 +22,7 @@ The following semantic conventions surrounding metrics are defined: * [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics. * [RPC](/specification/metrics/semantic_conventions/rpc-metrics.md): For RPC client and server metrics. * [Database](/specification/database/database-metrics.md): For SQL and NoSQL client metrics. -* [FaaS](/specification/metrics/semantic_conventions/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics. +* [FaaS](/specification/faas/faas-metrics.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) metrics. * **System metrics** * [System](/specification/system/system-metrics.md): For standard system metrics. * [Hardware](/specification/system/hardware-metrics.md): For hardware-related metrics. diff --git a/specification/general/trace-general.md b/specification/general/trace-general.md index 30cdadb255..cd361fb166 100644 --- a/specification/general/trace-general.md +++ b/specification/general/trace-general.md @@ -20,14 +20,14 @@ The following semantic conventions for spans are defined: * [Database](/specification/database/database-spans.md): For SQL and NoSQL client call spans. * [RPC/RMI](/specification/trace/semantic_conventions/rpc.md): For remote procedure call (e.g., gRPC) spans. * [Messaging](/specification/trace/semantic_conventions/messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans. -* [FaaS](/specification/trace/semantic_conventions/faas.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. +* [FaaS](/specification/faas/faas-spans.md): For [Function as a Service](https://en.wikipedia.org/wiki/Function_as_a_service) (e.g., AWS Lambda) spans. * [Exceptions](/specification/exceptions/exceptions-spans.md): For recording exceptions associated with a span. * [Compatibility](trace-compatibility.md): For spans generated by compatibility components, e.g. OpenTracing Shim layer. * [Feature Flags](/specification/trace/semantic_conventions/feature-flags.md): For recording feature flag evaluations associated with a span. The following library-specific semantic conventions are defined: -* [AWS Lambda](/specification/trace/semantic_conventions/instrumentation/aws-lambda.md): For AWS Lambda spans. +* [AWS Lambda](/specification/faas/aws-lambda.md): For AWS Lambda spans. * [AWS SDK](/specification/cloud-providers/aws-sdk.md): For AWS SDK spans. Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), diff --git a/specification/resource/semantic_conventions/faas.md b/specification/resource/semantic_conventions/faas.md index 15452ee862..dd6ceab955 100644 --- a/specification/resource/semantic_conventions/faas.md +++ b/specification/resource/semantic_conventions/faas.md @@ -8,7 +8,7 @@ See also: -- The [Trace semantic conventions for FaaS](../../trace/semantic_conventions/faas.md) +- The [Trace semantic conventions for FaaS](/specification/faas/faas-spans.md) - The [Cloud resource conventions](cloud.md) ## FaaS resource attributes @@ -72,12 +72,12 @@ The following well-known definitions MUST be used if you set this attribute and a TracerProvider. -Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](../../trace/semantic_conventions/faas.md#difference-between-invocation-and-instance). +Note: The resource attribute `faas.instance` differs from the span attribute `faas.invocation_id`. For more information see the [Semantic conventions for FaaS spans](/specification/faas/faas-spans.md#difference-between-invocation-and-instance). ## Using span attributes instead of resource attributes There are cases where a FaaS resource attribute is better applied as a span attribute instead. -See the [FaaS trace conventions](../../trace/semantic_conventions/faas.md) for more. +See the [FaaS trace conventions](/specification/faas/faas-spans.md) for more. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/supplementary-guidelines/compatibility/aws.md b/supplementary-guidelines/compatibility/aws.md index c5091435d8..9f939bcffb 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/supplementary-guidelines/compatibility/aws.md @@ -38,5 +38,5 @@ The following formats are currently natively supported by AWS services for propa AWS service-supported context propagation is necessary to allow context propagation through AWS managed services, for example: `S3 -> SNS -> SQS -> Lambda`. -(See the [aws-lambda sqs-event semantic convention](../../specification/trace/semantic_conventions/instrumentation/aws-lambda.md#sqs-event) +(See the [aws-lambda sqs-event semantic convention](../../specification/faas/aws-lambda.md#sqs-event) doc for details on how this context propagation is consumed by Lambda instrumentation.)