> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/general/metrics/


# メトリクスに関するセマンティック規約

**ステータス**: [Mixed][DocumentStatus]

メトリクスに関しては、次のセマンティック規約が定義されています。

* **[General Guidelines](#一般的なガイドライン): メトリクスに関する一般的なガイドライン。**
* [Database](https://opentelemetry.io/docs/specs/semconv/db/database-metrics/): SQLおよびNoSQLクライアントのメトリクス。
* [FaaS](/works/otel-specs-ja/semconv/faas/faas-metrics/): [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service)のメトリクス。
* GenAI: 生成AIのメトリクスについては、[OpenTelemetry GenAIセマンティック規約リポジトリ](https://github.com/open-telemetry/semantic-conventions-genai)を参照してください。
* [HTTP](/works/otel-specs-ja/semconv/http/http-metrics/): HTTPクライアントとサーバーのメトリクス。
* [Messaging](/works/otel-specs-ja/semconv/messaging/messaging-metrics/): メッセージングシステム（キュー、パブリッシュ・サブスクライブなど）のメトリクス。
* [RPC](/works/otel-specs-ja/semconv/rpc/rpc-metrics/): RPCクライアントとサーバーのメトリクス。
* [.NET](/works/otel-specs-ja/semconv/dotnet/): .NETランタイムコンポーネントが発行するネットワーク関連のメトリクス。
* **システムメトリクス**
  * [System](/works/otel-specs-ja/semconv/system/system-metrics/): 標準的なシステムメトリクス。
  * [Container](/works/otel-specs-ja/semconv/system/container-metrics/)
  * [Hardware](/works/otel-specs-ja/semconv/hardware/): ハードウェア関連のメトリクス。
  * [K8s](/works/otel-specs-ja/semconv/system/k8s-metrics/): K8sのメトリクス。
  * [Process](/works/otel-specs-ja/semconv/system/process-metrics/): 標準的なプロセスメトリクス。
  * [Runtime Environment](/works/otel-specs-ja/semconv/runtime/#メトリクス): ランタイム環境のメトリクス。
* [OTel SDK Telemetry](/works/otel-specs-ja/semconv/otel/sdk-metrics/): OpenTelemetry SDKコンポーネントが発行するメトリクス。

メトリクスに関するセマンティック規約とは別に、[トレース](/works/otel-specs-ja/semconv/general/trace/)、[ログ](/works/otel-specs-ja/semconv/general/logs/)、[イベント](/works/otel-specs-ja/semconv/general/events/)についても、OpenTelemetryは、独自の[リソースセマンティック規約](https://opentelemetry.io/docs/specs/semconv/resource/)を持つ包括的な[リソース](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/resource/sdk.md)という概念を定義しています。

## 一般的なガイドライン

**ステータス**: [Development][DocumentStatus]

新しいメトリクス名や属性を定義する際は、既存の標準的なメトリクスや、フレームワーク・ライブラリのメトリクスの先行事例を考慮してください。

関連するメトリクスは、その用途に基づいて階層としてまとめるべきです（SHOULD）。CPUやネットワークなどのOSメトリクス、GCの内部処理などアプリケーションランタイムのメトリクスといった、一般的なメトリクスのカテゴリーについては、トップレベルの階層を定義してください。ライブラリやフレームワークも、それぞれのメトリクスを階層にまとめるべきです。これは発見と即席の比較の助けになります。これにより、ユーザーはある特定のメトリクスから類似のメトリクスを見つけられます。

メトリクスの階層構造は名前空間を定義します。OpenTelemetryを補完するアーティファクトは、一部のメトリクスカテゴリーについてメトリクスの構造と階層を定義しており、これらは今後のメトリクス作成の際の判断材料になります。

共通の属性は、一貫して命名されるべきです（SHOULD）。これは発見しやすさを助け、メトリクス名に対する類似の属性の曖昧さを解消します。

Prometheusが推奨しているように、["経験則として、あるメトリクスのすべての属性に対する**集計**は意味を持つ**べきです**"](https://prometheus.io/docs/practices/naming/#metric-names)。

意味的な曖昧さは避けるべきです（SHOULD）。類似のメトリクスが、既存のすべてのメトリクスの中で実装に大きな違いがある場合は、接頭辞を付けたメトリクス名を使ってください。例えば、ガベージコレクションを行うランタイムはそれぞれ、わずかに異なる戦略や測定方法を持ちます。ランタイムで区別せずにGCのメトリクス名を一つの集合として使うと、エンドユーザーにとって異質な比較や混乱を生む可能性があります（例えば、`gc.*` よりも `jvm.gc*` を優先します）。多くのオペレーティングシステムのメトリクスの測定値も同様に曖昧です。

メトリクス名と属性は、一般的な[命名ガイドライン](/works/otel-specs-ja/semconv/general/naming/)に従うべきです（SHOULD）。

### 単位

慣習的なメトリクス、またはOpenTelemetryのメタデータに単位が含まれているメトリクス（例えばGoの `metric.WithUnit`）は、メトリクス名に単位を含めるべきではありません（SHOULD NOT）。メトリクス名に追加の意味を与える場合は、単位を含めてもかまいません。メトリクスは何よりも、理解しやすく使いやすいものでなければなりません（MUST）。

OpenTelemetryとOpenMetrics公開形式を使うシステムの間で相互運用するコンポーネントを構築する場合は、[OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/compatibility/prometheus_and_openmetrics.md)を使ってください。

### Instrumentの単位

**ステータス**: [Stable][DocumentStatus]

単位は、[Unified Code for Units of Measure](https://ucum.org/ucum)に従うべきです（SHOULD）。

- **utilization**（全体に対する割合を測定する）メトリクスのInstrumentは無次元であり、デフォルトの単位 `1`（unity）を使うべきです（SHOULD）。
- 数量を注記するために波括弧を使うすべての非単位は、それが表す数量の文法的な数と一致する必要があります。例えば、プロセスへの個々のリクエストの数を測定する場合、単位は `{requests}` ではなく `{request}` になります。
- 何かの整数カウントを測定するInstrumentは、先頭のデフォルト単位（`1`）*なしで*追加の意味を与えるために、波括弧を使った[注記](https://ucum.org/ucum.html#para-curly)のみを使うべきです（SHOULD）。例えば `{packet}`、`{error}`、`{fault}` などを使います。
- `1` 以外のInstrumentの単位や、[注記](https://ucum.org/ucum.html#para-curly)を使う単位は、UCUMの大文字小文字を区別する（"c/s"）表記を使って指定すべきです（SHOULD）。
  例えば、正式名が「degree Celsius」である単位には「Cel」を使います。
- Instrumentは、そうしない十分な技術的理由がない限り、接頭辞のない単位（すなわち `MiBy` ではなく `By`）を使うべきです（SHOULD）。
- Instrumentが継続時間を測定する場合、秒（すなわち `s`）を使うべきです（SHOULD）。

### Instrumentの型

**ステータス**: [Stable][DocumentStatus]

メトリクスのセマンティック規約の仕様は、`Counter` や `UpDownCounter` のような同期Instrument型の名前を使って書かれています。しかし、準拠する実装は、代わりに `Asynchronous Counter` や `Asynchronous UpDownCounter` のような非同期の等価物を使ってもかまいません（MAY）。
実装が同期型を選ぶか非同期の等価物を選ぶかは、実装の詳細と見なされます。いずれの選択も本仕様に準拠します。

### 一貫したUpDownCounterの時系列

**ステータス**: [Development][DocumentStatus]

`UpDownCounter` メトリクスを記録する際、増加を記録するために使われる属性値は、それに対応する減少を記録する際にも使われるべきです（SHOULD）。そうしないと、その増加と減少は別々の時系列になってしまいます。

例えば、`UpDownCounter` で `active_requests` を追跡していて、リクエストの開始時にインクリメントし、リクエストの終了時にデクリメントしている場合、リクエスト開始時のインクリメント時にまだ利用できない属性は、リクエスト終了時のデクリメント時にも使うべきではありません。

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status