# OpenTelemetry APIのパフォーマンスとブロッキング

> Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/performance/


この文書は、安全に使用できるOpenTelemetryクライアントを設計者が作成する際に役立つ、共通の原則を定義します。

## 主要な原則

主要な原則は以下のとおりです。

- **ライブラリはデフォルトでエンドユーザーのアプリケーションをブロックすべきではない。**
- **ライブラリは無制限のメモリリソースを消費すべきではない。**

モニタリングを実現する上で避けられないオーバーヘッドはありますが、APIはエンドユーザーのアプリケーションの性能をできるだけ低下させるべきではありません。そのため、エンドユーザーのアプリケーションをブロックしたり、過剰なメモリリソースを消費したりすべきではありません。

実装が並行処理をサポートする場合は、[並行性とスレッド安全性](/works/otel-specs-ja/spec/library-guidelines/#並行性とスレッド安全性)も参照してください。

### 非ブロッキングとメモリ消費のトレードオフ

完了していない非同期I/Oタスクやバックグラウンドタスクは、その状態を保持するためにメモリを消費する場合があります。このような場合、メモリの枯渇を防ぐために一部のタスクを破棄するか、情報の損失を防ぐためにすべてのタスクを保持するかというトレードオフが生じます。

OpenTelemetryクライアントにこのようなトレードオフがある場合、エンドユーザーに次のオプションを提供すべきです。

- **情報損失の防止**：すべての情報を保持するが、多くのリソースを消費する可能性がある
- **ブロッキングの防止**：過負荷時に一部の情報を破棄し、情報の損失が始まったときと復旧したときに警告ログを表示して知らせる
  - 破棄の閾値を変更できるオプションを提供すべきである
  - 実効サンプリング比率を表すメトリクスを提供する方が望ましい
  - OpenTelemetryクライアントは、ログについてこのオプションを提供する場合がある

### エンドユーザーアプリケーションが意識すべきログサイズ

エンドユーザーのアプリケーションが過剰な量のログを発信すると、ログはデフォルトで多くのメモリを消費する場合があります。このデフォルトの振る舞いは、ログを破棄するのではなく保持することを意図しています。リソース使用量を制限するには、エンドユーザーはエクスポーターに渡すログを減らすことを検討すべきです。

したがって、OpenTelemetryクライアントは、OpenTelemetryが捕捉するログをフィルタリングする手段を提供すべきです。エンドユーザーのアプリケーションは、ログファイルや標準出力（あるいは他の場所）には多くのログを出力したい一方で、そのすべてをOpenTelemetryのエクスポーターに送信したいわけではない場合があります。

OpenTelemetryクライアントのドキュメントでは、ログが多すぎるとデフォルトで多くのリソースを消費することを指摘し、その上でログをフィルタリングする方法を案内するとよいでしょう。

### シャットダウンと明示的フラッシュにおけるブロッキング

OpenTelemetryクライアントは、シャットダウン時にエンドユーザーのアプリケーションをブロックする場合があります。シャットダウン時には、情報の損失を防ぐためにデータをフラッシュする必要があります。シャットダウン時にブロックするのであれば、OpenTelemetryクライアントはユーザーが設定可能なタイムアウトをサポートすべきです。

OpenTelemetryクライアントが明示的なフラッシュ操作をサポートする場合、それもブロックする可能性があります。ただし、設定可能なタイムアウトをサポートすべきです。

## ドキュメント

言語固有の実装が、この文書に記述されていない特別な特性を持つ場合、その特性はドキュメント化すべきです。