この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/faas/faas-spans/
翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）
FaaSスパンに関するセマンティック規約
ステータス: Development
この文書では、サーバーのプロビジョニングや管理を伴わずに実行される関数のインスタンス（サーバーレス関数、Function as a Service（FaaS）とも呼ばれます）をスパンで記述する方法を定義します。
AWS Lambdaを計装するための追加の指示も参照してください。
全般的な属性
スパンのnameは、実行される関数の名前に設定するべきです（should）。faas.trigger属性の値によって、追加の属性を設定しなければなりません（MUST）。たとえば、httpトリガーはHTTPサーバーのセマンティック規約に従うべきです（SHOULD）。詳細は、Function Trigger Typeの節を参照してください。
この規約に従ったスパンが生成される場合、リソースのセマンティック規約に従ったfaas型のリソースが存在しなければなりません（MUST）。
関数名
関数の名前を記録できる場所は2つあります。スパン名と、faas.nameリソース属性です。
faas.name属性が存在する場合、その属性は関数名を含むことが保証されています。これは、まさにその目的のためにセマンティック規約で厳密に定義されているためです。また、スパン名にも関数名が含まれる可能性が非常に高いです（スパンの表示目的など）が、これは保証されていません（より弱い「SHOULD」要件であるため）。この保証を必要とする利用者は、faas.name属性を情報源として使用できます。
呼び出し（invocation）とインスタンス（instance）の違い
パフォーマンス上の理由（AWS LambdaやAzure Functionsなど）から、FaaSプロバイダーは、複数のリクエストを処理するために使われる関数の単一インスタンスに対して、1つの実行環境を割り当てます。
開発者は、この事実を利用して、異なる関数呼び出しの間でコストの高いリソース計算をキャッシュすることで、コールドスタートの問題を解決しています。
さらに、FaaSプロバイダーはこの挙動を推奨しています（Google Functionsなど）。
faas.instanceリソース属性は、同じ実行環境に属する関数呼び出しを関連付けるために設定されてもかまいません（MAY）。
スパン属性faas.invocation_idは、次の点でリソース属性のfaas.instanceとは異なります。
faas.invocation_idは、その関数の現在の呼び出しのIDを指します。faas.instanceは、その関数の実行環境のIDを指します。
受信側の呼び出し
この節では、FaaSインスタンス自身が報告する受信側のFaaS呼び出しについて説明します。
受信側のFaaSスパン属性
Status:
このスパンは、FaaS呼び出しのサーバー側（受信側）を表します。
スパン種別はSERVERであるべきです（SHOULD）。
スパンステータスはエラーの記録文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
faas.trigger |  | Required | string | この関数呼び出しの原因となったトリガーの種類。 | datasource; http; pubsub |
cloud.resource_id | | Recommended | string | 監視対象のクラウドリソースのクラウドプロバイダー固有のネイティブ識別子（AWSのARN、Azureの完全修飾リソースID、GCPの完全なリソース名など）[1] | arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function; //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID; /subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC> |
faas.coldstart | | Recommended | boolean | サーバーレス関数が初めて実行される場合（コールドスタート）にtrueとなるブール値。 | |
faas.invocation_id | | Recommended | string | 現在の関数呼び出しの呼び出しID。 | af9d5aa4-a685-4c5f-a22b-444f80b3cc28 |
[1] cloud.resource_id: 一部のクラウドプロバイダーでは、起動時に完全なIDを判定できない場合があるため、代わりにスパン属性としてcloud.resource_idを設定する必要があるかもしれません。
cloud.resource_idに使用する正確な値は、クラウドプロバイダーによって異なります。
この属性を設定し、かつ次の条件が該当する場合、次のよく知られた定義を使用しなければなりません（MUST）。
- AWS Lambda: 関数のARN。「invoked ARN」をそのまま使わず、エイリアスのsuffixを解決済みの関数バージョンに置き換えるよう注意してください。同一のランタイムインスタンスが複数の異なるエイリアスで呼び出し可能な場合があるためです。
- GCP: リソースのURI。
- Azure: 呼び出された関数の完全修飾リソースID（関数アプリではありません）。形式は
/subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>です。Azureの関数アプリは通常同じTracerProviderを共有する複数の関数をホストできるため、スパン属性を使わなければなりません（MUST）。
faas.triggerには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
datasource | データベースやファイルシステムの読み書きなど、データソースの操作に対する応答。 | |
http | 受信したHTTPリクエストへの応答を提供する。 | |
other | 他のいずれにも当てはまらない場合。 | |
pubsub | メッセージングシステムにメッセージが送信されたときに実行されるよう設定された関数。 | |
timer | 定期的に実行されるようスケジュールされた関数。 | |
受信側のFaaSスパン属性としてのリソース属性
上記に列挙した属性に加えて、FaaSやcloudのリソース属性は、受信側のFaaS呼び出しスパンにスパン属性として代わりに設定されてもかまいません（MAY）。一部のFaaS環境では、リソース属性に必要な情報の一部が、呼び出しのコンテキスト内（「requestコンテキスト」引数の一部など）でしか容易に入手できず、リソース情報を確認するための別のAPI呼び出しが可能な場合でも、コールドスタート時間の観点から法外なコストになる可能性があります。
AWSにおけるcloud.resource_id属性とcloud.account.id属性は、その一例です。
原則として、上記の考慮事項は、上記の基準（追加の作業なしには容易に入手できず、その作業がコストの高いものになりうる）を満たすすべてのリソース属性に当てはまります。
送信側の呼び出し
この節では、FaaSインスタンスを呼び出すクライアントが報告する送信側のFaaS呼び出しについて説明します。
Status:
このスパンは、FaaSサービスへの送信呼び出しを表します。
以下に列挙する属性についてクライアントが報告する値は、呼び出されたFaaSインスタンスが計装されている場合、そのインスタンス自身について報告する対応するFaaSリソース属性やクラウドリソース属性と等しいべきです（SHOULD）。
スパン種別はCLIENTであるべきです（SHOULD）。
スパンステータスはエラーの記録文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
faas.invoked_name | | Required | string | 呼び出された関数の名前。[1] | my-function |
faas.invoked_provider | | Required | string | 呼び出された関数のクラウドプロバイダー。[2] | alibaba_cloud; aws; azure |
faas.invoked_region | | Conditionally Required [3] | string | 呼び出された関数のクラウドリージョン。[4] | eu-central-1 |
[1] faas.invoked_name: 呼び出された関数のfaas.nameリソース属性と等しいべきです（SHOULD）。
[2] faas.invoked_provider: 呼び出された関数のcloud.providerリソース属性と等しいべきです（SHOULD）。
[3] faas.invoked_region: AWSやGCPなど一部のクラウドプロバイダーでは、関数がホストされているリージョンは、その関数を一意に識別するために欠かせない情報であり、エンドポイントの一部でもあります。呼び出し先のエンドポイントの一部であるため、リージョンはクライアント側で常に判明しています。この場合、faas.invoked_regionはそれに応じて設定されなければなりません（MUST）。リージョンがクライアント側で不明であるか、呼び出された関数を識別するために不要な場合、faas.invoked_regionの設定は任意です。
[4] faas.invoked_region: 呼び出された関数のcloud.regionリソース属性と等しいべきです（SHOULD）。
faas.invoked_providerには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
alibaba_cloud | Alibaba Cloud | |
aws | Amazon Web Services | |
azure | Microsoft Azure | |
gcp | Google Cloud Platform | |
tencent_cloud | Tencent Cloud | |
関数トリガーの種類
この節では、faas.trigger属性の値に基づいて、スパンの作成方法や追加の属性をどのように扱うかを説明します。
データソース
Status:
このスパンは、データベースやファイルシステムの読み書きなどのデータソース操作への応答としてトリガーされたFaaS呼び出しのサーバー側を表します。
スパン種別はSERVERであるべきです（SHOULD）。
スパンステータスはエラーの記録文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
faas.document.collection | | Required | string | トリガーとなった操作が実行された対象のソース名。たとえば、Cloud StorageやS3ではバケット名に、Cosmos DBではデータベース名に対応します。 | myBucketName; myDbName |
faas.document.operation | | Required | string | データに対して実行された操作の種類を記述します。 | insert; edit; delete |
faas.trigger | | Required | string | この関数呼び出しの原因となったトリガーの種類。[1] | datasource |
cloud.resource_id | | Recommended | string | 監視対象のクラウドリソースのクラウドプロバイダー固有のネイティブ識別子（AWSのARN、Azureの完全修飾リソースID、GCPの完全なリソース名など）[2] | arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function; //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID; /subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC> |
faas.coldstart | | Recommended | boolean | サーバーレス関数が初めて実行される場合（コールドスタート）にtrueとなるブール値。 | |
faas.document.name | | Recommended | string | 操作の対象となったドキュメント名・テーブル名。たとえば、Cloud StorageやS3ではファイル名に、Cosmos DBではテーブル名に対応します。 | myFile.txt; myTableName |
faas.document.time | | Recommended | string | データがアクセスされた時刻を、UTCで表現したISO 8601形式の文字列。 | 2020-01-23T13:47:06Z |
faas.invocation_id | | Recommended | string | 現在の関数呼び出しの呼び出しID。 | af9d5aa4-a685-4c5f-a22b-444f80b3cc28 |
[1] faas.trigger: datasourceに設定しなければなりません（MUST）。
[2] cloud.resource_id: 一部のクラウドプロバイダーでは、起動時に完全なIDを判定できない場合があるため、代わりにスパン属性としてcloud.resource_idを設定する必要があるかもしれません。
cloud.resource_idに使用する正確な値は、クラウドプロバイダーによって異なります。
この属性を設定し、かつ次の条件が該当する場合、次のよく知られた定義を使用しなければなりません（MUST）。
- AWS Lambda: 関数のARN。「invoked ARN」をそのまま使わず、エイリアスのsuffixを解決済みの関数バージョンに置き換えるよう注意してください。同一のランタイムインスタンスが複数の異なるエイリアスで呼び出し可能な場合があるためです。
- GCP: リソースのURI。
- Azure: 呼び出された関数の完全修飾リソースID（関数アプリではありません）。形式は
/subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>です。Azureの関数アプリは通常同じTracerProviderを共有する複数の関数をホストできるため、スパン属性を使わなければなりません（MUST）。
faas.document.operationには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
delete | オブジェクトが削除された場合。 | |
edit | オブジェクトが変更された場合。 | |
insert | 新しいオブジェクトが作成された場合。 | |
faas.triggerには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
datasource | データベースやファイルシステムの読み書きなど、データソースの操作に対する応答。 | |
http | 受信したHTTPリクエストへの応答を提供する。 | |
other | 他のいずれにも当てはまらない場合。 | |
pubsub | メッセージングシステムにメッセージが送信されたときに実行されるよう設定された関数。 | |
timer | 定期的に実行されるようスケジュールされた関数。 | |
HTTP
この関数の責務は、受信したHTTPリクエストへの応答を提供することです。faasスパンは、HTTPサーバーのセマンティック規約に記載されている推奨事項に従うべきです（SHOULD）。
PubSub
メッセージングシステムにメッセージが送信されたときに実行されるよう、関数が設定されます。
この場合、複数のメッセージがバッチ化され、同じ関数呼び出しに一度に転送されることがあります。
したがって、関数によって処理される各メッセージについて、メッセージングシステムのセマンティック規約に従い、faas型の異なるルートスパンを作成しなければなりません（MUST）。
これにより、個々のメッセージをその呼び出し元と関連付けられるようになります。
タイマー
定期的に実行されるよう、関数がスケジュールされます。次の追加の属性が推奨されます。
Status:
このスパンは、タイマーによってトリガーされたFaaS呼び出しのサーバー側を表します。
スパン種別はSERVERであるべきです（SHOULD）。
スパンステータスはエラーの記録文書に従うべきです（SHOULD）。
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
faas.trigger | | Required | string | この関数呼び出しの原因となったトリガーの種類。[1] | timer |
cloud.resource_id | | Recommended | string | 監視対象のクラウドリソースのクラウドプロバイダー固有のネイティブ識別子（AWSのARN、Azureの完全修飾リソースID、GCPの完全なリソース名など）[2] | arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function; //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID; /subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC> |
faas.coldstart | | Recommended | boolean | サーバーレス関数が初めて実行される場合（コールドスタート）にtrueとなるブール値。 | |
faas.cron | | Recommended | string | Cron式としてスケジュール期間を含む文字列。 | 0/5 * * * ? * |
faas.invocation_id | | Recommended | string | 現在の関数呼び出しの呼び出しID。 | af9d5aa4-a685-4c5f-a22b-444f80b3cc28 |
faas.time | | Recommended | string | 関数の呼び出し時刻を、UTCで表現したISO 8601形式の文字列。 | 2020-01-23T13:47:06Z |
[1] faas.trigger: timerに設定しなければなりません（MUST）。
[2] cloud.resource_id: 一部のクラウドプロバイダーでは、起動時に完全なIDを判定できない場合があるため、代わりにスパン属性としてcloud.resource_idを設定する必要があるかもしれません。
cloud.resource_idに使用する正確な値は、クラウドプロバイダーによって異なります。
この属性を設定し、かつ次の条件が該当する場合、次のよく知られた定義を使用しなければなりません（MUST）。
- AWS Lambda: 関数のARN。「invoked ARN」をそのまま使わず、エイリアスのsuffixを解決済みの関数バージョンに置き換えるよう注意してください。同一のランタイムインスタンスが複数の異なるエイリアスで呼び出し可能な場合があるためです。
- GCP: リソースのURI。
- Azure: 呼び出された関数の完全修飾リソースID（関数アプリではありません）。形式は
/subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>です。Azureの関数アプリは通常同じTracerProviderを共有する複数の関数をホストできるため、スパン属性を使わなければなりません（MUST）。
faas.triggerには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。
| Value | Description | Stability |
|---|---|---|
datasource | データベースやファイルシステムの読み書きなど、データソースの操作に対する応答。 | |
http | 受信したHTTPリクエストへの応答を提供する。 | |
other | 他のいずれにも当てはまらない場合。 | |
pubsub | メッセージングシステムにメッセージが送信されたときに実行されるよう設定された関数。 | |
timer | 定期的に実行されるようスケジュールされた関数。 | |
その他
Function as a Serviceは非常に柔軟であり、セマンティック規約だけでは完全に対応できません。
関数が前述のいずれの場合にも該当しない場合、スパンは属性faas.triggerを"other"に設定しなければなりません（MUST）。
この場合、最も適切な属性を定義する責任は、フレームワークまたは計装ライブラリにあります。
例
この例は、Google Cloud Platform上でホストされている（FaaSではない）プロセス（種別CLIENTのスパンA）が、Amazon Web Servicesで「my-lambda-function」というLambda関数を呼び出す場合（種別SERVERのスパンB）のFaaS属性を示しています。
| Attribute Kind | Attribute | Span A (Client, GCP) | Span B (Server, AWS Lambda) |
|---|---|---|---|
| Resource | cloud.provider | "gcp" | "aws" |
| Resource | cloud.region | "europe-west3" | "eu-central-1" |
| Span | faas.invoked_name | "my-lambda-function" | n/a |
| Span | faas.invoked_provider | "aws" | n/a |
| Span | faas.invoked_region | "eu-central-1" | n/a |
| Span | faas.trigger | n/a | "http" |
| Span | faas.invocation_id | n/a | "af9d5aa4-a685-4c5f-a22b-444f80b3cc28" |
| Span | faas.coldstart | n/a | true |
| Resource | faas.name | n/a | "my-lambda-function" |
| Resource | faas.version | n/a | "semver:2.0.0" |
| Resource | faas.instance | n/a | "my-lambda-function:instance-0001" |
| Resource | cloud.resource_id | n/a | "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function" |