状態メトリクス

ステータス: Development

定義

この文書では、「状態メトリクス（status metric）」とは、ある時点において、区別可能な状態値のクローズドな集合の中のいずれかにあることを表すために使われるメトリクスを指します。

設計

この性質を持つメトリクスを表現する設計は、次のようになります。

id: metric.example.status
type: metric
metric_name: example.status
stability: development
brief: "The current state."
note: |
  A timeseries is produced for every possible value of `example.state`. The
  value of this metric is 1 for a state if it is currently in said state, and
  is 0 for all other states.
instrument: updowncounter
unit: "1"
attributes:
- ref: example.state

Instrument

このメトリクスは、GaugeではなくUpDownCounterとして計装されます。これは意図的な選択であり、特定の状態にあるオブジェクトを数え上げるのは妥当な使用事例だからです。あるメトリクス値は、特定の状態属性値に対して0または1のいずれかであるため、単純な合計集計によって特定の状態のインスタンス数を数えられます。

Entityの属性にすべきか

そのstatusをEntityの記述属性（識別属性ではありません）にすることも可能です。Entityの状態変化を追跡することは、Entityにおける既知の使用事例です。しかし、メトリクス中心のソリューションがEntityとどのようにやり取りすべきかを理解する助けになるため、状態メトリクスも合わせて定義することが推奨されます。

命名

計装の文脈の中で、k8sがphaseやstatusといった語を持つような、よく知られた命名規則が既にある場合は、常にそれらの語を選ぶべきです。

すぐに使える命名の選択肢がない場合は、次の推奨命名スキームを使ってもかまいません。このスキームでは、次の2つを表す語を選ぶ必要があります。

取りうる値の集合のうちの1つを表す名詞（属性名）
どの値が現在有効であるかを記述する形容詞（メトリクス名）

一般的な推奨は、属性には「state」、メトリクスには「status」という語を使うことです。これは、それぞれの語に対する一般的な言い回しに由来しています。

“What state is X in?"（Xはどんなstateにあるか） “What is the current status of X?"（Xの現在のstatusは何か）

この英語の語感については議論の余地が大いにありますが、一貫性のために、明らかな言い回しが見つからない場合はこの命名スキームを採用することが推奨されます。