> Source: https://www.ymotongpoo.com/works/oteps/metrics/otep-0126/


# OTEP-0126: 設定可能なメトリクス集約のためのSDKサポートの提案

デフォルトのSDKに、メトリクスの集約を設定可能にするためのサポートを追加します。

## 動機 {#motivation}

OpenTelemetryのアーキテクチャは、計装と運用の関心事を分離しています。
Metric APIが提供するメトリクスインストゥルメントは、いずれもデフォルトの集約を持つよう定義されています。
そして、デフォルトでは、すべてのラベルを用いて集約の単位を定義した状態で集約が実行されます。
これはSDKが提供するデフォルト設定としては優れたものですが、より高い設定可能性が必要とされています。

この提案が対処しようとしている主なユースケースは3つあります。

1) アプリケーション開発者／オペレーターが、あるインストゥルメントまたはインストゥルメントの集合に対して、SDKが提供するデフォルトとは異なる集約を使用したいと考える場合。
2) エクスポーター作成者が、結果として得られるメトリクスデータポイントがどの「時間的性質(Temporality)」（デルタ vs. 累積）を表すかをSDKに伝えたいと考える場合。
   「デルタ」とは、直前のレポート間隔以降のメトリクス記録のみが集約の対象になることを意味し、「累積」とは、インストゥルメントの生存期間全体にわたるすべてのメトリクス記録が集約の対象になることを意味します。
3) アプリケーション開発者／オペレーターが、選択したメトリクスベンダー／バックエンドに報告されるメトリクスについて、ラベルのカーディナリティを制約したいと考える場合。

## 解説 {#explanation}

私は、デフォルトのSDKに対する新しい機能を提案します。
これはSDKのMeterProvider実装のインターフェース上で利用可能なもので、メトリクス記録が行われる際にSDKが使用するバッチ処理戦略と集約を設定できるようにします。
これは「Views」APIの始まりですが、OpenCensusの完全なView機能を実装することを意図してはいません。

基本的なAPIは2つの部分から構成されます。

* InstrumentSelector - 設定を適用する対象となる、1つ以上のインストゥルメントの選択を指定できるようにします。
  - 選択オプションには、インストゥルメントの種類(Counter、ValueRecorderなど)と、インストゥルメント名に対する正規表現が含まれます。
  - 複数のオプションが指定された場合、それらは加算的なものとして扱われます。
  - 例: 名前が ".duration" で終わるすべてのValueRecorderを選択する。
* View - バッチ処理と集約をどのように行うべきかを設定します。
  - 3つのことを指定できます。 集約(Sum、MinMaxSumCount、Histogramなど)、バッチ処理の「時間的性質」、そして集約に使用するサブセットとして考慮する事前定義済みラベルの集合です。
    - 注: 「時間的性質」は「DELTA」と「CUMULATIVE」のいずれかであり、それぞれ、収集が行われた後に集約の値がリセットされるかどうかを指定します。
  - すべてが指定されていない場合、指定されなかったものについてはデフォルトが要求されているものとみなすべきです。
  - 例:
    - MinMaxSumCount集約を使用し、デルタ形式のバッチ処理を提供する。
    - Histogram集約を使用し、集約には "route" と "error" の2つのラベルのみを使用する。
    - quantile集約を使用し、集約時にすべてのラベルを破棄する。

この提案では、各セレクターに関連付けられるViewは1つのみです。

具体的な例として、Javaでは、これは次のようになるかもしれません。

```java
 // get a handle to the MeterSdkProvider (note, this is concrete name of the default SDK class in java, not a general SDK)
 MeterSdkProvider meterProvider = OpenTelemetrySdk.getMeterProvider();

 // create a selector to select which instruments to customize:
 InstrumentSelector instrumentSelector = InstrumentSelector.newBuilder()
  .instrumentType(InstrumentType.COUNTER)
  .build();

 // create a configuration of how you want the metrics aggregated:
 View view =
      View.create(Aggregations.minMaxSumCount(), Temporality.DELTA);

 //register the configuration with the MeterSdkProvider
 meterProvider.registerView(instrumentSelector, view);
```

## 内部の詳細 {#internal-details}

このOTEPは、これが特定の言語でどのように実装されるべきかを規定するものではなく、望まれる機能のみを規定します。

この提案の部分的な実装を含むJavaでのプロトタイプが、PRの形で[こちら](https://github.com/open-telemetry/opentelemetry-java/pull/1412)から入手できます。

## トレードオフと緩和策 {#trade-offs-and-mitigations}

これは完全な「Views」APIを提供することを意図したものではありませんが、その基礎となるものです。
ここでの目標は、単純に、オペレーターとエクスポーター作成者がバッチ処理と集約を設定できるようにすることです。

これは、これらの設定を提供するための正確なインターフェースを規定することを意図しておらず、また、プログラムによらない設定オプションを検討するものでもありません。

## 先行技術と代替技術 {#prior-art-and-alternatives}

* 先行技術は、おそらく主に[OpenCensus Views](https://opencensus.io/stats/view/)システムにあります。
* 別の[OTEP](https://github.com/open-telemetry/oteps/pull/89)が、Views APIの構築に対応しようと試みました。

## 未解決の問題(公式な仕様で解決されるべき) {#open-questions-to-be-resolved-in-an-official-specification}

1. カスタム集約はすべてのインストゥルメントに対して許可されるべきでしょうか。 サポートされていない集約のリクエストに対して、SDKはどのように応答すべきでしょうか。
2. DELTAとCUMULATIVEのどちらを要求するかは、すべてのオペレーターに対して一般に利用可能にするのではなく、エクスポーター専用のAPIを通じてのみ利用可能にすべきでしょうか。
3. 正規表現に基づく名前のマッチングは広すぎて危険でしょうか。 代替案(設定するすべてのインストゥルメントの正確な名前を知らなければならないこと)は負担が大きすぎるでしょうか。
4. この提案の中に、完全なViews API(つまり、インストゥルメントごとに複数の名前付き集約を持つこと)の実装を難しくするようなものはあるでしょうか。
5. 集約の設定を変更するために、エクスポーターは自身が設定されているSDKとどのようにやり取りすべきでしょうか。
6. 最初の実装にラベルの削減を含めるべきでしょうか、それとも後続のOTEP／仕様で行うべきでしょうか。
7. これは集約を完全に無効化することをサポートしますか。 サポートする場合、そのためのインターフェースはどのようなものでしょうか。
8. 1つのインストゥルメントに複数のセレクターが適用され得る場合、セレクターの優先順位はどうなるでしょうか。

## 今後の可能性 {#future-possibilities}

この提案が可能にする今後の変更にはどのようなものがあるでしょうか。

- 本格的なViews APIです。 これにより、1つのインストゥルメントにつき複数の「view」を持てるようになります。 エクスポーターがどのようにして望むviewを指定するのか、あるいはすべての生成されたメトリクスを取得することになるのかは、まだ明らかではありません。
- プログラムによらない設定オプションの追加です。