サービスに関するセマンティック規約

サービスとは、テレメトリーデータ（イベント、メトリクス、スパンなど）を生成する、アプリケーションの論理的な構成要素です。

現代の分散アプリケーションアーキテクチャでは次のようになります。

service.namespace は、エンドユーザーや他のアプリケーションが利用するために設計された、コンポーネント全体のシステムです。
service は、アプリケーションを構成する論理的で明確に区別された構成要素の1つです。例えば、ロードバランシングのために同じコンテナイメージを実行するインスタンス群として実行されます。
service.instance は、サービスコンポーネントの明確に区別された1つのインスタンスです。例えば、サービスを提供するKubernetesデプロイメントの一部である特定のKubernetesコンテナです。

例として、データベースとそのデータベースを使うHTTPサーバーから構成されるブログサイトを考えてみます。

flowchart LR
    App(("`**service.namespace**
           blog-site`"))
    Db["`**service.name**
         db`"]
    Http["`**service.name**
          http-server`"]
    Http1["`**service.instance.id**
            http-server-1231`"]
    Http2["`**service.instance.id**
           http-server-1234`"]
    Db1["`**service.instance.id**
         db-gbgfx`"]
    Db --> Db1
    Http --> Http1
    Http --> Http2
    App --> Db
    App --> Http

ここでは、HTTPサーバーには2つのインスタンスがあり、その間にロードバランサーが存在する可能性があることがわかります。加えて、データベースのインスタンスは1つだけです。

Service

Status:

type: service

Description: 特定の機能を実行する、アプリケーションまたはシステムの論理的な単位。

Attributes:

Role	Key	Requirement Level	Value Type	Description	Example Values
Identity	`service.name`	`Required`	string	サービスの論理名。[1]	`shoppingcart`
Description	`service.criticality`	`Recommended`	string	サービスの運用上の重要度。[2]	`critical`; `high`; `medium`; `low`
Description	`service.version`	`Recommended`	string	サービスコンポーネントのバージョン文字列。形式はこの規約では定義されません。	`2.0.0`; `a01dbef8a`

[1] service.name: 水平方向にスケールされたサービスのすべてのインスタンスで同じ値でなければなりません（MUST）。値が指定されなかった場合、SDKは unknown_service: にプロセス実行ファイル名を連結した値にフォールバックしなければなりません（MUST）。プロセス実行ファイル名が利用できない場合、値は unknown_service に設定しなければなりません（MUST）。プロセス実行ファイル名とは、process.executable.nameリソース属性で説明されているのと同じ値であるプロセス実行ファイルの名前です。

[2] service.criticality: アプリケーション開発者は、自分たちのサービスの運用上の重要性を表すために service.criticality を設定することが推奨されます。テレメトリーの利用者は、この属性を使ってテレメトリー収集を最適化したり、ユーザー体験を改善したりしてもかまいません（MAY）。

service.criticality には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

Value	Description	Stability
`critical`	ビジネス上重要なサービス。ダウンタイムが収益、ユーザー体験、または中核機能に直接影響します。[3]
`high`	重要だが、劣化への耐性やフォールバック機構を持つサービス。[4]
`low`	中核業務にとって必須ではないサービス。バックグラウンドタスクや内部ツールに使われます。[5]
`medium`	補助的な機能を提供するサービス。劣化してもユーザーへの影響は限定的です。[6]

[3]: 例として、決済処理、認証、主要なユーザー向けAPIが挙げられます。

[4]: 例として、ショッピングカート、検索、レコメンデーションエンジンが挙げられます。

[5]: 例として、バッチ処理、クリーンアップジョブ、内部ダッシュボードが挙げられます。

[6]: 例として、分析、レポーティング、必須ではない連携機能が挙げられます。

Service Instance

Status:

type: service.instance

Description: 論理的なサービスの一意なインスタンス。

Attributes:

Role	Key	Stability	Requirement Level	Value Type	Description	Example Values
Identity	`service.instance.id`		`Required`	string	サービスインスタンスの文字列ID。[1]	`627cc493-f310-47de-96bd-71410b7dec09`

[1] service.instance.id: 同じ service.namespace,service.name の組み合わせを持つすべてのインスタンスに対して一意でなければなりません（MUST）（言い換えると、service.namespace,service.name,service.instance.id の三つ組はグローバルに一意でなければなりません（MUST））。このIDは、同時に存在する同じサービスのインスタンス（例えば水平方向にスケールされたサービスのインスタンス）を区別する助けになります。

SDKなどの実装は、ランダムなVersion 1またはVersion 4のRFC 4122 UUIDを生成することが推奨されますが、安定性が望ましい場合はこの値の元として固有の一意なIDを使ってもかまいません。その場合、そのIDはUUID Version 5の元として使われるべきであり（SHOULD）、次のUUIDを名前空間として使うべきです（SHOULD）: 4d63009a-8d0f-11ee-aad7-4c796ed8e320。

サービスインスタンスを識別する目的では不透明な値だけが必要とされるため、通常UUIDが推奨されます。 /etc/machine-idファイルのman ページに見られるのと同様に、Pod名や名前空間といった基盤となるデータは機密として扱われるべきであり、それを別のリソース属性経由で公開するかどうかはユーザーの選択に委ねられます。

アプリケーションサーバー（unicornのような）の背後で実行されるアプリケーションの場合、そのアプリケーションに参加するすべてのプロセスに対して単一の識別子を使うことは推奨されません。代わりに、各分割（例えばunicornのワーカースレッド）が独自のinstance.idを持つことが推奨されます。

Collectorがテレメトリーを生成しているサービスインスタンスを一意に判定できない場合、Collectorが service.instance.id を設定することは推奨されません。例えば、pod.name に基づいてUUIDを作成すると、Collectorがそのpod内のどのコンテナからテレメトリーが発生したかを把握できていない可能性が高いため、誤りとなる可能性があります。一方で、Collectorがそのテレメトリーのサービスインスタンスを一意に判定できる場合は、service.instance.id を設定してもかまいません。これは、対象のアドレスとポートを把握しているスクレイピングレシーバーの場合に典型的に当てはまります。

Service Namespace

Status:

type: service.namespace

Description: システムまたはアプリケーションを構成する関連サービスを、共通の名前空間の下にグループ化します。

Attributes:

Role	Key	Stability	Requirement Level	Value Type	Description	Example Values
Identity	`service.namespace`		`Required`	string	`service.name` の名前空間。[1]	`Shop`

[1] service.namespace: サービスのグループを区別する助けになる意味を持つ文字列値です。例えば、そのサービスグループを所有するチーム名などです。service.name は同じ名前空間の中で一意であることが期待されます。Resourceの中で service.namespace が指定されていない場合、service.name は明示的な名前空間を持たないすべてのサービスの中で一意であることが期待されます（つまり、空・未指定の名前空間も単純にもう1つの有効な名前空間として扱われます）。長さ0の名前空間文字列は、未指定の名前空間と等価であるとみなされます。