Yoshi Yamaguchi

ログAPI

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/logs/api/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

ステータス: 安定（Stable）（別途明記されている箇所を除く）

ログAPIは、既存のロギングライブラリとOpenTelemetryのログデータモデルの間を橋渡しするログアペンダーをロギングライブラリの作者が構築するために提供されています。

ログAPIは、計装ライブラリや、計装対象のライブラリ・アプリケーションから直接呼び出すこともできます。ただし、言語によっては直接使う場合によりエルゴノミックなAPIを自由に提供できます（MAY）。

ログAPIは、次の主要なコンポーネントから構成されます。

  • LoggerProviderはAPIのエントリーポイントです。Loggerへのアクセスを提供します。
  • Loggerは、LogRecordとしてログを発行する役割を担います。
graph TD
    A[LoggerProvider] -->|Get| B(Logger)
    B -->|Emit| C(LogRecord)

LoggerProvider

LoggerはLoggerProviderを通じてアクセスできます。

通常、LoggerProviderは中央の場所からアクセスされることが期待されます。したがって、APIはグローバルな既定のLoggerProviderを設定・登録・アクセスする手段を提供すべきです（SHOULD）。

LoggerProviderの操作

LoggerProviderは次の機能を提供しなければなりません（MUST）。

  • Loggerの取得

Loggerの取得

このAPIは、次の計装スコープパラメータを受け付けなければなりません（MUST）。

  • name: 計装スコープの名前を指定します。例えば計装ライブラリ（io.opentelemetry.contrib.mongodbなど）、パッケージ、モジュール、クラス名などです。アプリケーションやライブラリに組み込みのOpenTelemetry計装がある場合、計装対象ライブラリと計装ライブラリが同じライブラリを指すことがあります。このシナリオでは、nameはそのライブラリまたはアプリケーション内のモジュール名またはコンポーネント名を表します。ロガー名を定義するログ発生源（JavaのLogger Nameなど）については、そのロガー名を計装スコープ名として記録すべきです（should）。

  • version（オプション）: 計装スコープにバージョンがある場合（ライブラリバージョンなど）、そのバージョンを指定します。値の例: 1.0.0。

  • schema_url（オプション）: 発行されるテレメトリーに記録すべきSchema URLを指定します。

  • attributes（オプション）: 発行されるテレメトリーに関連付ける計装スコープ属性を指定します。このAPIは、属性がまったくない場合を含め、可変数の属性を受け付けられる構造でなければなりません（MUST）。

Loggerに対して同一という語を使う場合、すべてのパラメータが等しいインスタンスを指します。Loggerに対して異なるという語を使う場合、少なくとも1つのパラメータの値が異なるインスタンスを指します。

Logger

LoggerはLogRecordを発行する役割を担います。

Loggerは次の機能を提供しなければなりません（MUST）。

Loggerは次の機能を提供すべきです（SHOULD）。

LogRecordの発行

このAPIを呼び出すことの効果は、処理パイプラインへLogRecordを発行することです。

このAPIは次のパラメータを受け付けなければなりません（MUST）。

  • Timestamp（オプション）
  • Observed Timestamp（オプション）
  • LogRecordに関連付けるコンテキスト。暗黙のコンテキストがサポートされている場合、このパラメータはオプションであるべきで（SHOULD）、指定されなければ現在のコンテキストを使わなければなりません（MUST）。明示的なコンテキストのみがサポートされる場合、このパラメータは必須であるべきです（SHOULD）。
  • Severity Number（オプション）
  • Severity Text（オプション）
  • Body（オプション）
  • Attributes（オプション）
  • Event Name（オプション）

このAPIは次のパラメータを受け付けてもよい（MAY）です。

  • Exception（オプション）: LogRecordに関連付けられる例外（またはエラー）。

Enabled

LogRecordを生成する際に計算コストの高い処理を実行することをユーザーが避けられるようにするため、LoggerはこのEnabled APIを提供すべきです（SHOULD）。

このAPIは次のパラメータを受け付けるべきです（SHOULD）。

  • LogRecordに関連付けるコンテキスト。暗黙のコンテキストがサポートされている場合、このパラメータはオプションであるべきで（SHOULD）、指定されなければ現在のコンテキストを使わなければなりません（MUST）。明示的なコンテキストのみがサポートされる場合、このパラメータを受け付けることが必須です（REQUIRED）。
  • Severity Number（オプション）
  • Event Name（オプション）

このAPIは、言語に慣用的なブーリアン型を返さなければなりません（MUST）。返される値がtrueであれば、指定された引数に対してLoggerが有効であることを意味し、falseであればLoggerが無効であることを意味します。

APIのドキュメントには、Enabledの呼び出しは任意であり、LogRecordの発行の前に必須ではないことを記載すべきです（SHOULD）。これは、LogRecordの構築が高コストな場合、例えばそのbodyや属性をデータベースから取得した値から計算しなければならない場合にのみ関係する、パフォーマンス上の最適化です。そうした場合、計装は先にEnabledを呼び出し、falseが返されればその処理をスキップできます。LogRecordの構築が低コストな場合、計装は直接発行できます。ドキュメントにはまた、返される値は静的ではなく時間の経過とともに変化し得るため、キャッシュした値が古くなる可能性があることも記載すべきです（SHOULD）。

オプションパラメータと必須パラメータ

定義された操作にはさまざまなパラメータが含まれ、その一部はオプションと表示されています。オプションと表示されていないパラメータは必須です。

オプションパラメータそれぞれについて、APIはそれを受け付けられる構造でなければなりません（MUST）が、ユーザーに指定を義務付けてはなりません（MUST NOT）。

必須パラメータそれぞれについて、APIはユーザーに指定を義務付ける構造でなければなりません（MUST）。

並行処理に関する要件

並行実行をサポートする言語では、ログAPIは特定の保証と安全性を提供します。

LoggerProvider - すべてのメソッドについて、実装が既定で並行使用に対して安全である必要があることをドキュメント化しなければなりません（MUST）。

Logger - すべてのメソッドについて、実装が既定で並行使用に対して安全である必要があることをドキュメント化しなければなりません（MUST）。

エルゴノミックなAPI

ステータス: 開発中（Development）

言語は、より使いやすく便利なロギングAPIを追加で提供してもよい（MAY）です。

エルゴノミックなAPIは、イベントの意味論に従うイベントレコードの発行をより便利にすべきです（SHOULD）。

エルゴノミックなAPIの設計は、その言語にとって慣用的であるべきです（SHOULD）。

参考文献