システムセマンティック規約の一般的な使用例

この文書は、システムセマンティック規約で扱いたい使用例を集めたものです。ここで挙げる使用例は、どの計装を必須とみなすかについてワーキンググループが判断する際の指針になります。この文書で述べる使用例は、執筆時点でsemconvに既存の計装が存在するかどうかにかかわらず、一般的な形で述べます。個別の計装を検討する際には、想定される使用例を総合的に見た上で、その重要性を理解できるようにするためです。

凡例

General Information＝Entity、メトリクス、メトリクス属性のいずれかを通じて発見できるべき情報。

Dashboard＝包括的なダッシュボードを作るために、メトリクスを通じて取得できるべき情報。

Alerts＝利用可能な情報から作成できるべき、一般的なアラートの例。

Host

ユーザーは、ホストの健全性を監視できるべきです。これには、リソース消費の監視や、ホストあるいはホスト群における中核コンポーネント（ネットワークスタック、メモリ、CPUなど）のリソース枯渇や不具合による予期しないエラーの監視が含まれます。

General information

マシン名
ID（そのコンテキストに関連するもの。クラウドプロバイダーのIDでもよく、単にベースマシンのIDでもよい）
OS情報（プラットフォーム、バージョン、アーキテクチャなど）
CPU情報
メモリ容量

Dashboard

メモリのutilization
CPUのutilization
ディスクのutilization
ディスクのスループット
ネットワークトラフィック

Alerts

VMが予期せず停止した
ネットワークアクティビティが予期せず急増した
メモリ/CPU/ディスクのutilizationがしきい値の割合を超えた

Notes

特にアラートについては、異種混在のホスト群に対して一律に適用できる必要があります。プラットフォームが混在していても、ホスト群全体にわたって効果的にアラートできるよう、クロスプラットフォームな計装の性質を重視します。

hostという語は、文脈によって異なる意味を持つことがあります。

ネットワークの文脈におけるhost。多数の他のマシンが接続される中心的なマシンを指す場合と、仮想化の文脈におけるhostを指す場合があります。
仮想化の文脈におけるhost。VMやコンテナのような仮想ゲストをホスティングしているものを指します。

このドキュメントの文脈では、hostは一般に、物理か仮想かを問わず個々のマシンを指すものと考えます。これはさらに混乱を招く場合があります。一意なマシンとしてのhostが、同時にネットワークのhostや仮想化のhostでもあり得るためです。この複雑さは、hostという名前空間が既存のOpenTelemetryの計装や一般的な言い回しに深く根づいているという事実から受け入れざるを得ません。可能な限り、ネットワークや仮想化に関するhostの計装は、hostという語のどの意味を指しているかが明確な別の名前空間の中に収めることで区別を保ち、ルートのhost名前空間は個々のマシンを指すものとします。

Process

ユーザーは、OSが提供するデータを使って任意のプロセスの健全性を監視できるべきです。ユーザーがこれを求める理由としては次のようなものが考えられます。

監視したいプロセスに、プロセス内で動作するランタイム固有の計装が有効化されていない、またはそもそも計装できない場合。アンチウイルスソフトなど、他のバックグラウンドプロセスがこれに該当します。
多数のプロセスを監視しており、それらすべてに対して一律の計装を持ちたい場合。
個人的な好みや既存事情によるもの。すでにOSの信号を使って何かを監視しており、基本的なプロセス計装への移行の方が手間が少なく、その後徐々に他の特化したsemconvへ移行していく場合。

General information

プロセス名
Pid
ユーザー/所有者

Dashboard

物理メモリのusageあるいはutilization
仮想メモリのusage
CPUのusageあるいはutilization
ディスクのスループット
ネットワークのスループット

Alert

プロセスが予期せず停止した
メモリ/CPUのusage・utilizationがしきい値を超えた
メモリが一定期間にわたって一方的に増加し続けている（メモリリークの検出）

Notes

アラートやダッシュボードに加えて、プロセスの基本的なベンチマークも一般的な使用例として考慮します。クロスプラットフォームな形で提供できる基本的な統計情報は、この用途にも効果的に使えるため、プロセスの計装に関する判断を行う際にはこの点も考慮します。