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

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
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 -->
@ -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.
<!-- endsemconv -->
[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

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

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
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` -->
@ -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).
<!-- semconv faas_span -->
| 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/<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,
`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 |
<!-- endsemconv -->
[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

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

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.
* [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),

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

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

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