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

Moved FaaS semconv (#148) 

Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
This commit is contained in:
Alexander Wert 2023-07-03 17:56:44 +02:00 committed by GitHub
parent 4011a1ba64
commit 676d53a582
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 46 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
specification/README.md
View File

@ -8,6 +8,7 @@ Semantic Conventions are defined for the following areas:
* [General](general/README.md): General Semantic Conventions. * [General](general/README.md): General Semantic Conventions.
* [Exceptions](exceptions/README.md): Semantic Conventions for Exceptions. * [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. * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
* [Database](database/README.md): Semantic Conventions for database operations. * [Database](database/README.md): Semantic Conventions for database operations.

16
specification/faas/README.md Normal file
View File

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

24
specification/trace/semantic_conventions/instrumentation/aws-lambda.md → specification/faas/aws-lambda.md
View File

@ -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 There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the
use cases. use cases.
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i specification/trace/semantic_conventions/instrumentation/aws-lambda.md` --> <!-- Re-generate TOC with `markdown-toc --no-first-h1 -i specification/faas/aws-lambda.md` -->
<!-- toc --> <!-- toc -->
@ -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. **[1]:** This may be different from `cloud.resource_id` if an alias is involved.
<!-- endsemconv --> <!-- endsemconv -->
[faas]: ../faas.md (FaaS trace conventions) [faas]: faas-spans.md (FaaS trace conventions)
[faasres]: ../../../resource/semantic_conventions/faas.md (FaaS resource conventions) [faasres]: /specification/resource/semantic_conventions/faas.md (FaaS resource conventions)
[cloud]: ../../../resource/semantic_conventions/cloud.md (Cloud resource conventions) [cloud]: /specification/resource/semantic_conventions/cloud.md (Cloud resource conventions)
### AWS X-Ray Environment Span Link ### 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 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 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. 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`. - [`faas.trigger`][faas] MUST be set to `pubsub`.
- [`messaging.operation`](../messaging.md) MUST be set to `process`. - [`messaging.operation`](/specification/trace/semantic_conventions/messaging.md) MUST be set to `process`.
- [`messaging.system`](../messaging.md) MUST be set to `AmazonSQS`. - [`messaging.system`](/specification/trace/semantic_conventions/messaging.md) MUST be set to `AmazonSQS`.
- [`messaging.destination.kind` or `messaging.source.kind`](../messaging.md#messaging-attributes) MUST be set to `queue`. - [`messaging.destination.kind` or `messaging.source.kind`](/specification/trace/semantic_conventions/messaging.md#messaging-attributes) MUST be set to `queue`.
### SQS Message ### 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 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 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. 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`. - [`faas.trigger`][faas] MUST be set to `pubsub`.
- [`messaging.operation`](../messaging.md#messaging-attributes) MUST be set to `process`. - [`messaging.operation`](/specification/trace/semantic_conventions/messaging.md#messaging-attributes) MUST be set to `process`.
- [`messaging.system`](../messaging.md#messaging-attributes) MUST be set to `AmazonSQS`. - [`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. event.
Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` in instrumentation for SQS Note that `AWSTraceHeader` is the only supported mechanism for propagating `Context` in instrumentation for SQS

4
specification/metrics/semantic_conventions/faas-metrics.md → specification/faas/faas-metrics.md
View File

@ -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_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` | | `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). 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). 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. 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. `faas.trigger` SHOULD be included in all metric events while `faas.invoked_*` attributes apply on outgoing FaaS invocation events only.

16
specification/trace/semantic_conventions/faas.md → specification/faas/faas-spans.md
View File

@ -5,7 +5,7 @@
This document defines how to describe an instance of a function that runs without provisioning 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. 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).
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` --> <!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
@ -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. 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).
<!-- semconv faas_span --> <!-- semconv faas_span -->
| Attribute | Type | Description | Examples | Requirement Level | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `faas.trigger` | string | Type of the trigger which caused this function invocation. [1] | `datasource` | Recommended | | `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 | | `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/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>` | 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/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>` | Recommended |
**[1]:** For the server/consumer span on the incoming side, **[1]:** For the server/consumer span on the incoming side,
`faas.trigger` MUST be set. `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 ### Function Name
There are 2 locations where the function's name can be recorded: the span name and the 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 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 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 ### 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 instead be set as span attributes on incoming FaaS invocation spans: In some
FaaS environments some of the information required for resource 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) 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 | | `tencent_cloud` | Tencent Cloud |
<!-- endsemconv --> <!-- endsemconv -->
[FaaS resource attributes]: ../../resource/semantic_conventions/faas.md [FaaS resource attributes]: ../resource/semantic_conventions/faas.md
[Cloud resource attributes]: ../../resource/semantic_conventions/cloud.md [Cloud resource attributes]: ../resource/semantic_conventions/cloud.md
## Function Trigger Type ## 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. 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. 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. This way, it is possible to correlate each individual message with its invocation sender.
### Timer ### Timer

2
specification/general/metrics-general.md
View File

@ -22,7 +22,7 @@ The following semantic conventions surrounding metrics are defined:
* [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics. * [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. * [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. * [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 metrics**
* [System](/specification/system/system-metrics.md): For standard system metrics. * [System](/specification/system/system-metrics.md): For standard system metrics.
* [Hardware](/specification/system/hardware-metrics.md): For hardware-related metrics. * [Hardware](/specification/system/hardware-metrics.md): For hardware-related metrics.

4
specification/general/trace-general.md
View File

@ -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. * [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. * [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. * [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. * [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. * [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. * [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: 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. * [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), Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md),

6
specification/resource/semantic_conventions/faas.md
View File

@ -8,7 +8,7 @@
See also: 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) - The [Cloud resource conventions](cloud.md)
## FaaS resource attributes ## FaaS resource attributes
@ -72,12 +72,12 @@ The following well-known definitions MUST be used if you set this attribute and
a TracerProvider. a TracerProvider.
<!-- endsemconv --> <!-- endsemconv -->
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 ## Using span attributes instead of resource attributes
There are cases where a FaaS resource attribute is better applied as a span There are cases where a FaaS resource attribute is better applied as a span
attribute instead. 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 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md

2
supplementary-guidelines/compatibility/aws.md
View File

@ -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 AWS service-supported context propagation is necessary to allow context propagation
through AWS managed services, for example: `S3 -> SNS -> SQS -> Lambda`. 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.) doc for details on how this context propagation is consumed by Lambda instrumentation.)