ログSDK

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

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

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

OpenTelemetryの利用者には、OpenTelemetry APIに対する計装からの相互作用が実際にテレメトリーを生成する手段が必要です。OpenTelemetry Logging SDK（以下SDK）は、この機能を利用者に提供するOpenTelemetry APIの実装です。

OpenTelemetryのすべての言語実装は、SDKを提供しなければなりません（MUST）。

LoggerProvider

LoggerProviderは、リソースを指定できる手段を提供しなければなりません（MUST）。Resourceが指定された場合、それはLoggerProviderのいずれかのLoggerが生成するすべてのLogRecordに関連付けられるべきです（SHOULD）。

LoggerProviderの作成

SDKは、複数の独立したLoggerProviderの作成を許可すべきです（SHOULD）。

Loggerの作成

LoggerインスタンスはLoggerProvider経由でのみ作成可能であるべきです（SHOULD）（APIを参照）。

LoggerProviderは、LoggerAPIの取得を実装しなければなりません（MUST）。

利用者が指定した入力は、作成されるLoggerに保存されるInstrumentationScopeインスタンスを作成するために使わなければなりません（MUST）。

無効なname（nullまたは空文字列）が指定された場合、nullを返したり例外をスローしたりせず、フォールバックとして機能するLoggerを返さなければなりません（MUST）。そのnameは元の無効な値を保持すべきで（SHOULD）、指定された値が無効であることを報告するメッセージがログに記録されるべきです（SHOULD）。

ステータス: 開発中（Development） - LoggerProviderは、設定されたLoggerConfiguratorを使って該当するLoggerConfigを計算し、そのLoggerConfigに準拠して振る舞うLoggerを作成しなければなりません（MUST）。

Configuration

設定（つまりLogRecordProcessor、および（開発中）LoggerConfigurator）は、LoggerProviderが所有しなければなりません（MUST）。設定は、適切であればLoggerProviderの作成時に適用してもよい（MAY）です。

LoggerProviderは設定を更新するメソッドを提供してもよい（MAY）です。設定が更新された場合（例えばLogRecordProcessorの追加）、更新された設定はすでに返却済みのすべてのLoggerにも適用されなければなりません（MUST）（つまり、設定変更の前後どちらにLoggerProviderからLoggerを取得したかは問題になってはなりません（MUST NOT））。注記: 実装としては、Loggerインスタンスが自身のLoggerProviderへの参照を持ち、この参照経由でのみ設定にアクセスすることでこれを実現できます。

LoggerConfigurator

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

LoggerConfiguratorは、LoggerのLoggerConfigを計算する関数です。

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

logger_scope: LoggerのInstrumentationScope。

この関数は該当するLoggerConfig、または既定のLoggerConfigを使うべきことを示す何らかの信号を返さなければなりません（MUST）。この信号は、言語にとって慣用的な形に応じて、nil、null、空、または既定のLoggerConfigのインスタンスであってもよい（MAY）です。

この関数はLoggerが最初に作成されるとき、および（更新がサポートされていれば）LoggerProviderのLoggerConfiguratorが更新されたときに存在するすべてのLoggerに対して呼び出されます。したがって、速く返ることが重要です。

LoggerConfiguratorは柔軟性を最大化するため関数としてモデル化されています。ただし実装は、よくある使用例に対応するための省略記法やヘルパー関数を提供してもよい（MAY）です。

名前で1つ以上のロガーを、完全一致またはパターンマッチングで選択する。
1つ以上の特定のロガーを無効化する。
すべてのロガーを無効化し、1つ以上の特定のロガーを選択的に有効化する。
特定のロガーまたはロガーパターンに対して最小の重大度レベルを設定する。
特定のロガーまたはロガーパターンに対してトレースベースのフィルタリングを有効化する。

Shutdown

このメソッドは、プロバイダーに必要なクリーンアップを行う手段を提供します。

Shutdownは、LoggerProviderインスタンスごとに1回だけ呼び出されなければなりません（MUST）。Shutdownの呼び出し後、Loggerを取得する以降の試みは許可されません。SDKは、可能であればこれらの呼び出しに対して有効なno-opのLoggerを返すべきです（SHOULD）。

Shutdownは、成功したか、失敗したか、タイムアウトしたかを呼び出し元に知らせる手段を提供すべきです（SHOULD）。

Shutdownは、一定のタイムアウト内に完了または中断すべきです（SHOULD）。Shutdownは、ブロッキングAPIとして実装しても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装してもよい（MAY）です。OpenTelemetry SDKの作者は、シャットダウンのタイムアウトを設定可能にするかどうかを決めてもよい（MAY）です。

Shutdownは、登録済みのすべてのLogRecordProcessorに対してShutdownを呼び出すことで実装しなければなりません（MUST）。

ForceFlush

このメソッドは、プロバイダーが登録済みのLogRecordProcessorに対して、まだエクスポートされていないすべてのReadableLogRecordを直ちにエクスポートするよう通知する手段を提供します。

ForceFlushは、成功したか、失敗したか、タイムアウトしたかを呼び出し元に知らせる手段を提供すべきです（SHOULD）。エラー状態がある場合、ForceFlushは何らかのERRORステータスを返すべきで（SHOULD）、エラー状態がない場合は何らかのNO ERRORステータスを返すべきです（SHOULD）。言語実装は、ERRORとNO ERRORをどうモデル化するかを決めてもよい（MAY）です。

ForceFlushは、一定のタイムアウト内に完了または中断すべきです（SHOULD）。ForceFlushは、ブロッキングAPIとして実装しても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装してもよい（MAY）です。OpenTelemetry SDKの作者は、フラッシュのタイムアウトを設定可能にするかどうかを決めてもよい（MAY）です。

ForceFlushは、登録済みのすべてのLogRecordProcessorに対してForceFlushを呼び出さなければなりません（MUST）。

Logger

ステータス: 開発中（Development） - Loggerは、Loggerの作成時に計算されたLoggerConfigに従って振る舞わなければなりません（MUST）。LoggerProviderがLoggerConfiguratorの更新をサポートする場合、更新時にLoggerは新しいLoggerConfigに従って振る舞うよう更新されなければなりません（MUST）。

LoggerConfig

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

LoggerConfigは、Loggerの振る舞いのさまざまな設定可能な側面を定義します。これは次のパラメータから構成されます。

enabled: ロガーが有効かどうかを示すブーリアン値。
明示的に設定されていない場合、enabledパラメータは既定でtrueであるべきです（SHOULD）（つまりLoggerは既定で有効です）。
Loggerが無効化されている場合、No-op Loggerと同等に振る舞わなければなりません（MUST）。
minimum_severity: 処理対象とするログレコードの最小の重大度レベルを示すSeverityNumber。
明示的に設定されていない場合、minimum_severityパラメータは既定で0にならなければなりません（MUST）。
ログレコードのSeverityNumberが指定されており（つまり0ではない）、設定されたminimum_severityより小さい場合、そのログレコードはLoggerによって破棄されなければなりません（MUST）。重大度が指定されていない（つまり0の）ログレコードは、このパラメータの影響を受けず、したがって最小重大度によるフィルタリングを回避します。
trace_based: サンプリングされていないトレースに関連付けられたログレコードをロガーが破棄すべきかどうかを示すブーリアン値。
明示的に設定されていない場合、trace_basedパラメータは既定でfalseにならなければなりません（MUST）。
trace_basedがfalseの場合、ログレコードはこのパラメータによる影響を受けてはなりません（MUST NOT）。
trace_basedがtrueの場合、サンプリングされていないトレースに関連付けられたログレコードはLoggerによって破棄されなければなりません（MUST）。ログレコードは、有効なSpanIdを持ち、そのTraceFlagsがトレースがサンプリングされていないことを示している場合に、サンプリングされていないトレースに関連付けられているとみなされます。トレースコンテキストに関連付けられていないログレコードは、このパラメータの影響を受けず、したがってトレースベースのフィルタリングを回避します。

これらのパラメータへの変更がEnabledの呼び出し元に即座に反映されることを実装が保証する必要はありません。ただし、その変更は最終的には反映されなければなりません（MUST）。

LogRecordの発行

Observed Timestampが指定されていない場合、実装はそれを現在時刻に設定すべきです（SHOULD）。

Exceptionが提供された場合、SDKは既定で、例外のセマンティック規約に示された規約に従い、その例外から得られる属性をLogRecordに設定しなければなりません（MUST）。利用者が指定した属性が優先されなければならず（MUST）、例外由来の属性によって上書きされてはなりません（MUST NOT）。

注記: パフォーマンス最適化のため、SDKは大きな例外属性（例えばexception.stacktrace）を生成する際に、設定済みの属性の制限を考慮してもよい（MAY）です。これは、どうせ切り捨てられる大きな属性値の不要な処理を避けるのに役立ちます。

ステータス: 開発中（Development）ログレコードを処理する前に、実装はLoggerConfigで定義されたフィルタリング規則を適用しなければなりません（MUST）。

Enabled: Loggerが有効でない場合（つまりLoggerConfig.enabledがfalseの場合）、そのログレコードは破棄されなければなりません（MUST）。
最小重大度: ログレコードのSeverityNumberが指定されており（つまり0ではない）、設定されたminimum_severityより小さい場合、そのログレコードは破棄されなければなりません（MUST）。
トレースベース: trace_basedがtrueであり、そのログレコードがSpanIdを持ち、TraceFlagsのSAMPLEDフラグが立っていない場合、そのログレコードは破棄されなければなりません（MUST）。

Enabled

Enabledは、次のいずれかに当てはまる場合、falseを返さなければなりません（MUST）。

登録済みのLogRecordProcessorが存在しない。
ステータス: 開発中（Development） - Loggerが無効化されている（LoggerConfig.enabledがfalse）。
ステータス: 開発中（Development） - 指定された重大度が指定されており（つまり0ではない）、LoggerConfigで設定されたminimum_severityより小さい。
ステータス: 開発中（Development） - LoggerConfigでtrace_basedがtrueであり、現在のコンテキストがサンプリングされていないトレースに関連付けられている。
登録済みのすべてのLogRecordProcessorがEnabledを実装しており、それぞれに対するEnabledの呼び出しがすべてfalseを返す。

それ以外の場合、trueを返すべきです（SHOULD）。追加の最適化や機能をサポートするためにfalseを返してもよい（MAY）です。

LogRecordの追加インターフェース

この文書では、ReadableLogRecordとReadWriteLogRecordという2つのインターフェースを参照します。それぞれ以下のように定義します。

ReadableLogRecord

これを引数として受け取る関数は、LogRecordに追加されたすべての情報にアクセスできなければなりません（MUST）。また、LogRecordに（暗黙的に）関連付けられた計装スコープとリソースの情報にもアクセスできなければなりません（MUST）。

トレースコンテキストのフィールドは、発行時に解決されたContext（明示的に渡されたContextまたは現在のContextのいずれか）から設定されていなければなりません（MUST）。

収集の制限による属性の切り捨て件数は、非OTLP形式への変換仕様に記載されているとおり、エクスポーターが報告できるように利用可能でなければなりません（MUST）。

注記: 通常、これは新しいインターフェースまたは（イミュータブルな）値型として実装されます。SDKは、ReadableLogRecordとReadWriteLogRecordの両方を表現するために単一の型を使ってもよいです。

ReadWriteLogRecord

ReadWriteLogRecordは、ReadableLogRecordのスーパーセットです。

これを引数として受け取る関数は、LogRecordに追加された次の情報についても、追加で変更できなければなりません（MUST）。

SDKは、ReadWriteLogRecordのディープクローンを作成する操作を提供してもよい（MAY）です。この操作は、並行安全性が要求されないログレコードに対する競合状態を避けるために、Batching processorのような非同期プロセッサーが利用できます。

LogRecordの制限

LogRecordの属性は、属性の制限に関する共通規則に従わなければなりません（MUST）。

SDKが属性の制限を実装する場合、以下のJavaの例のように、利用者が個々の制限を設定できるようにする形で、LoggerProviderへの設定を通じてこれらの制限を変更できる手段を提供しなければなりません（MUST）。

このオプションは、1つのクラスにまとめてもよい（MAY）です。その場合、そのクラスはLogRecordLimitsと呼ばれるべきです（SHOULD）。

public interface LogRecordLimits {
  public int getAttributeCountLimit();

  public int getAttributeValueLengthLimit();
}

設定可能なパラメータ:

属性に適用可能なすべての共通オプション

属性がこうした制限によって破棄されたことを利用者に示すメッセージが、SDKのログに出力されるべきです（SHOULD）。過剰なログ出力を防ぐため、このメッセージは（破棄された属性ごとではなく）LogRecordごとに最大1回だけ出力されなければなりません（MUST）。

LogRecordProcessor

LogRecordProcessorは、LogRecordの発行に対するフックを可能にするインターフェースです。

組み込みのプロセッサーは、LogRecordのバッチ処理と、エクスポート可能な表現への変換、そしてエクスポーターへのバッチの引き渡しを担います。

LogRecordProcessorはSDKのLoggerProviderに直接登録でき、登録された順序と同じ順序で呼び出されます。

LoggerProviderに登録された各プロセッサーは、プロセッサーと任意のエクスポーターから構成されるパイプラインの一部です。SDKは、各パイプラインが個別のエクスポーターで終わることを許可しなければなりません（MUST）。

SDKは、利用者が属性によるエンリッチのような高度なシナリオのためにカスタムプロセッサーを実装・設定したり、組み込みのプロセッサーをデコレートしたりできるようにしなければなりません（MUST）。

以下の図は、LogRecordProcessorとSDKの他のコンポーネントとの関係を示しています。

  +-----+------------------------+   +------------------------------+   +-------------------------+
  |     |                        |   |                              |   |                         |
  |     |                        |   | Batching LogRecordProcessor  |   |    LogRecordExporter    |
  |     |                        +---> Simple LogRecordProcessor    +--->     (OtlpExporter)      |
  |     |                        |   |                              |   |                         |
  | SDK | Logger.emit(LogRecord) |   +------------------------------+   +-------------------------+
  |     |                        |
  |     |                        |
  |     |                        |
  |     |                        |
  |     |                        |
  +-----+------------------------+

フィルタリングやファンアウトのような高度なログレコード処理を設定する方法の詳細については、Supplementary Guidelinesを参照してください。

LogRecordProcessorの操作

OnEmit

OnEmitは、LogRecordが発行されたときに呼び出されます。このメソッドは、そのLogRecordを発行したスレッド上で同期的に呼び出されるため、ブロックしたり例外をスローしたりすべきではありません（SHOULD NOT）。

パラメータ:

logRecord - 発行されたLogRecordに対するReadWriteLogRecord。
context - 解決済みのContext（明示的に渡されたContextまたは現在のContext）

戻り値: Void

SDKのLoggerProviderに直接登録されたLogRecordProcessorについては、logRecordへの変更は次に登録されているプロセッサーから見えなければなりません（MUST）。

LogRecordProcessorは、OnEmit呼び出しの間、logRecordを自由に変更できます。ただし、ReadWriteLogRecordが並行安全であることはオプションです（OPTIONAL）。したがって、logRecordに対する並行的な変更や読み取りは競合状態を引き起こす可能性があります。こうした競合状態を避けるため、実装は、Batching processorのような並行処理を行う場合にはlogRecordのクローンを使うことを利用者に推奨すべきです（SHOULD）。

Enabled

Enabledは、Logger.Enabled経由のフィルタリングをサポートするために、LogRecordProcessorが実装してもよい（MAY）操作です。

パラメータ:

呼び出し元が明示的に渡した、または現在のコンテキスト
Loggerに関連付けられた計装スコープ
呼び出し元が渡したSeverity Number
呼び出し元が渡したEvent Name

戻り値: Boolean

実装は、与えられたパラメータに対して（もし生成されるとしたら）LogRecordがフィルタリングされて除外されるべき場合にfalseを返すべきです。設定待ちのような不確定な状態については、既定でtrueを返すべきです。

Enabledの内部でパラメータに加えた変更は、呼び出し元に伝播してはなりません（MUST NOT）。パラメータはイミュータブルであるか、値渡しされます。

この操作は通常同期的に呼び出されるため、ブロックしたり例外をスローするべきではありません。

フィルタリングを担いEnable操作をサポートするLogRecordProcessorの実装は、OnEmitがフィルタリングを個別に処理することを保証すべきです。APIの利用者は、LogRecordの発行を呼び出す前にEnabledを呼び出すことを期待されていません。さらに、OnEmitとEnabledのフィルタリングロジックは異なることがあります。

他のLogRecordProcessor（フィルタリングを行う場合がある）をラップするLogRecordProcessorの実装は、可能であればラップしているプロセッサーのEnabledに委譲する形でEnabledを実装できます。ただし、そうしたプロセッサーのOnEmitの実装は、ラップしているプロセッサーのEnabledを呼び出すべきではありません。OnEmitはフィルタリングを個別に処理する責任を持つためです。

ShutDown

プロセッサーをシャットダウンします。SDKがシャットダウンされるときに呼び出されます。これは、プロセッサーが必要なクリーンアップを行う機会です。

Shutdownは、LogRecordProcessorインスタンスごとに1回だけ呼び出されるべきです（SHOULD）。Shutdownの呼び出し後、OnEmitへの以降の呼び出しは許可されません。SDKは、可能であればこれらの呼び出しを穏やかに無視すべきです（SHOULD）。

Shutdownは、成功したか、失敗したか、タイムアウトしたかを呼び出し元に知らせる手段を提供すべきです（SHOULD）。

Shutdownは、ForceFlushの効果を含まなければなりません（MUST）。

Shutdownは、一定のタイムアウト内に完了または中断すべきです（SHOULD）。Shutdownは、ブロッキングAPIとして実装しても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装してもかまいません。OpenTelemetry SDKの作者は、シャットダウンのタイムアウトを設定可能にするかどうかを決めてもかまいません。

ForceFlush

これは、ForceFlushの呼び出し以前にLogRecordProcessorがイベントを受け取っていたLogRecordに関連するすべての作業を、このメソッドから戻る前になるべく速やかに完了すべき（SHOULD）ことを示すヒントです。

特に、LogRecordProcessorに関連付けられたエクスポーターがある場合、まだエクスポートしていないすべてのLogRecordについてそのエクスポーターのExportを呼び出し、続いてそのForceFlushを呼び出すべきです（SHOULD）。組み込みのLogRecordProcessorはそうしなければなりません（MUST）。タイムアウトが指定されている場合（後述）、LogRecordProcessorはすべての呼び出しを完了させることよりもタイムアウトを守ることを優先しなければなりません（MUST）。この目標を達成するため、行っている一部またはすべてのExportやForceFlushの呼び出しをスキップまたは中断してもよい（MAY）です。

ForceFlushは、成功したか、失敗したか、タイムアウトしたかを呼び出し元に知らせる手段を提供すべきです（SHOULD）。

ForceFlushは、一部のFaaSプロバイダーのように、呼び出し後にプロセスが一時停止される可能性があるがLogRecordProcessorが発行済みのLogRecordをまだエクスポートしていないような、絶対に必要な場合にのみ呼び出されるべきです（SHOULD）。

ForceFlushは、一定のタイムアウト内に完了または中断すべきです（SHOULD）。ForceFlushは、ブロッキングAPIとして実装しても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装してもかまいません。OpenTelemetry SDKの作者は、フラッシュのタイムアウトを設定可能にするかどうかを決めてもかまいません。

組み込みのプロセッサー

標準のOpenTelemetry SDKは、以下に説明するシンプルプロセッサーとバッチプロセッサーの両方を実装しなければなりません（MUST）。

その他の一般的な処理シナリオについては、まずOpenTelemetry Collectorでのプロセス外実装を検討すべきです（SHOULD）。

この文書で定義される追加のプロセッサーは、SDKパッケージによって提供されるべきです（SHOULD）。

Simple processor

これは、完了したログを渡し、完了した時点でエクスポート用のReadableLogRecord表現を設定済みのLogRecordExporterに渡すLogRecordProcessorの実装です。

このプロセッサーは、LogRecordExporterのExportへの呼び出しを同期化し、並行して呼び出されないことを保証しなければなりません（MUST）。

設定可能なパラメータ:

exporter - LogRecordが送られるエクスポーター。

Batching processor

これは、LogRecordのバッチを作成し、エクスポート用のReadableLogRecord表現を設定済みのLogRecordExporterに渡すLogRecordProcessorの実装です。

このプロセッサーは、LogRecordExporterのExportへの呼び出しを同期化し、並行して呼び出されないことを保証しなければなりません（MUST）。

設定可能なパラメータ:

exporter - LogRecordが送られるエクスポーター。
maxQueueSize - 最大キューサイズ。このサイズに達すると、ログは破棄されます。既定値は2048です。
scheduledDelayMillis - 連続する2回のエクスポートの間隔（ミリ秒）。既定値は1000です。
exportTimeoutMillis - エクスポートがキャンセルされるまでに実行できる時間。既定値は30000です。
maxExportBatchSize - 各エクスポートの最大バッチサイズ。maxQueueSize以下でなければなりません。既定値は512です。

Event to span event bridge

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

これは、Eventを現在のスパン上のスパンイベントに変換するLogRecordProcessorの実装です。

このプロセッサーはSDKによって提供されるべきです（SHOULD）。

このプロセッサーは、以下の条件すべてが満たされる場合、かつその場合にのみ、LogRecordをスパンイベントにブリッジしなければなりません（MUST）。

そのLogRecordが空でないEvent Nameを持つ。
そのLogRecordが有効なTraceIdとSpanIdを持つ。
解決済みのコンテキストが、IsRecordingがtrueである現在のスパンを含む。
そのLogRecordのTraceIdとSpanIdが、解決済みのContextにおける現在のスパンのTraceIdとSpanIdに等しい。

これらの条件のいずれかが満たされない場合、そのプロセッサーは何もしてはなりません（MUST）。

LogRecordがブリッジされる場合、そのプロセッサーは以下のマッピングでちょうど1つのスパンイベントを追加しなければなりません（MUST）。

スパンイベント名は、LogRecordのEvent Nameでなければなりません（MUST）。
LogRecordにTimestampが設定されている場合、それがスパンイベントのタイムスタンプとして使われなければなりません（MUST）。そうでなく、LogRecordにObservedTimestampが設定されている場合は、それがスパンイベントのタイムスタンプとして使われなければなりません（MUST）。
すべてのLogRecordのAttributesは、スパンイベントの属性としてスパンイベントにコピーされなければなりません（MUST）。

LogRecordをスパンイベントにブリッジすることは、そのLogRecordが通常のログ処理パイプラインを継続して通過することを妨げてはなりません（MUST NOT）。

設定可能なパラメータ: なし。

LogRecordExporter

LogRecordExporterは、OpenTelemetry SDKに組み込んでテレメトリーデータの送信をサポートできるようにするために、プロトコル固有のエクスポーターが実装しなければならないインターフェースを定義します。

このインターフェースの目標は、プロトコル依存のテレメトリーエクスポーターの実装負担を最小化することです。プロトコルエクスポーターは、主にシンプルなテレメトリーデータのエンコーダーおよび送信者であることが期待されます。

各実装は、SDKがエクスポーターに要求する並行性の特性を文書化しなければなりません（MUST）。

LogRecordExporterの操作

LogRecordExporterは、以下の関数をサポートしなければなりません（MUST）。

Export

ReadableLogRecordのバッチをエクスポートします。この関数を実装するプロトコルエクスポーターは、通常データをシリアライズして宛先に送信することが期待されます。

Exportは、同一のエクスポーターインスタンスに対する他のExport呼び出しと並行して呼び出されるべきではありません（SHOULD NOT）。

実装によっては、エクスポートの結果はExport呼び出しの戻り値ではなく、非同期タスクの完了を通知するための言語固有の方法でプロセッサーに返されることがあります。つまり、あるエクスポーターのインスタンスに対してExportが並行して呼び出されるべきではないとしても、エクスポートというタスク自体を並行して行えないということではありません。これをどのように行うかは、この仕様の範囲外です。

Exportは無期限にブロックしてはならず（MUST NOT）、その呼び出しがエラー結果（Failure）でタイムアウトするまでの合理的な上限がなければなりません（MUST）。

並行リクエストとリトライロジックはエクスポーターの責任です。既定のSDKのLogRecordProcessorはリトライロジックを実装すべきではありません（SHOULD NOT）。必要なロジックは、ログの送信先である特定のプロトコルとバックエンドに大きく依存する可能性が高いためです。例えば、OpenTelemetry Protocol（OTLP）仕様は、並行リクエストの送信とリクエストのリトライの両方についてロジックを定義しています。

パラメータ:

batch - ReadableLogRecordのバッチ。バッチの正確なデータ型は言語固有であり、典型的にはリストなどの何らかの型です。例えばJavaのログでは、典型的にはCollection<LogRecordData>になります。

戻り値: ExportResult

Exportの戻り値は実装固有です。その言語にとって慣用的な方法で、エクスポーターはExportResultをプロセッサーに送らなければなりません。ExportResultはSuccessまたはFailureのいずれかの値を持ちます。

Success - バッチが正常にエクスポートされました。プロトコルエクスポーターの場合、これは通常データがワイヤー上で送信され、宛先サーバーに配信されたことを意味します。
Failure - エクスポートが失敗しました。バッチは破棄されなければなりません。例えば、バッチに不正なデータが含まれていてシリアライズできない場合にこれが起こり得ます。

例えば、JavaではExportの戻り値は、完了時にExportResultオブジェクトを返すFutureになります。一方Erlangでは、エクスポーターは特定のバッチに対するExportResultを含むメッセージをプロセッサーに送ります。

ForceFlush

これは、ForceFlushの呼び出し以前にエクスポーターが受け取っていたReadableLogRecordのエクスポートを、このメソッドから戻る前になるべく速やかに完了すべき（SHOULD）ことを示すヒントです。

ForceFlushは、成功したか、失敗したか、タイムアウトしたかを呼び出し元に知らせる手段を提供すべきです（SHOULD）。

ForceFlushは、一部のFaaSプロバイダーのように、呼び出し後にプロセスが一時停止される可能性があるが、エクスポーターが発行済みのReadableLogRecordをまだエクスポートしていないような、絶対に必要な場合にのみ呼び出されるべきです（SHOULD）。

Shutdown

エクスポーターをシャットダウンします。SDKがシャットダウンされるときに呼び出されます。これは、エクスポーターが必要なクリーンアップを行う機会です。

Shutdownは、LogRecordExporterインスタンスごとに1回だけ呼び出されるべきです（SHOULD）。Shutdownの呼び出し後、以降のExportの呼び出しは許可されず、Failure結果を返すべきです（SHOULD）。

Shutdownは、（宛先が利用できずデータのフラッシュを試みる場合などに）無期限にブロックすべきではありません（SHOULD NOT）。OpenTelemetry SDKの作者は、シャットダウンのタイムアウトを設定可能にするかどうかを決めてもよい（MAY）です。

OTEP0150 ロギングライブラリSDKプロトタイプ仕様

並行処理に関する要件

ステータス: 安定（Stable）

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

LoggerProvider - Loggerの作成、ForceFlush、Shutdownは並行して呼び出しても安全でなければなりません（MUST）。

Logger - すべてのメソッドは並行して呼び出しても安全でなければなりません（MUST）。

LogRecordExporter - ForceFlushとShutdownは並行して呼び出しても安全でなければなりません（MUST）。

Self-observability

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

Logs SDKは、SDKのself-observabilityをサポートすべきです（SHOULD）。