ログ | OpenTelemetry

ログは、構造化（推奨）または非構造化された、任意のメタデータを含む、タイムスタンプ付きのテキストレコードです。 すべてのテレメトリーシグナルの中で、ログは最も大きな遺産を持っています。 ほとんどのプログラミング言語には、組み込みのログ機能があるか、もしくはよく知られ、広く使われているログライブラリがあります。
OpenTelemetry は、ログレコードを生成するための Logs API と SDK、そして既存のロギングフレームワークと統合するための言語 SDK とロギングブリッジを提供します。 ログとは、ロギングプロバイダを通して送信されるあらゆるデータを指し、イベントはログの特殊なタイプです。 すべてのログがイベントであるとは限りませんが、すべてのイベントはログです。 Logs API は公開されており、アプリケーションコードから直接使用することも、既存のロギングライブラリやブリッジを介して間接的に使用することもできます。
OpenTelemetry は、既に生成されているログを扱うように設計されており、ログを他のシグナルと関連付けたり、コンテキスト属性を追加したり、異なるソースを共通のフォーマットに正規化して処理およびエクスポートするためのツールを提供します。
OpenTelemetry コレクター はログを扱うための複数のツールを提供します。
OpenTelemetry を採用する最初のステップとして、汎用的なログエージェントとしてコレクターをデプロイすることがよく含まれます。
アプリケーションにおいて、OpenTelemetry のログは任意のログライブラリやビルトインのログ機能を使って作成されます。 自動計装を追加したりSDKを活用したりすると、OpenTelemetry は既存のログをアクティブなトレースやスパンと自動的に関連付け、それらの ID をログの本体に含めます。 つまり、OpenTelemetry はログとトレースを自動的に関連付けます。
ログは OpenTelemetry 仕様の stable シグナルです。 ログAPIとSDKの各言語固有の実装については、ステータスは以下の通りです。
OpenTelemetryはあらゆるログ形式に対応していますが、すべての形式が分析に等しく役立つわけではありません。次のセクションでは、構造化ログ、半構造化ログ、非構造化ログの違いについて説明します。重要：JSON形式でエンコードされたログは、安定したスキーマを持つという意味で自動的に「構造化」されるわけではありません。半構造化されている場合もあります。構造化ログとは、一貫したスキーマ、または明確に定義された型付きフィールドを持ち、下流の処理が確実に依存できるログを指します。
構造化ログとは、定義済みで一貫性のあるスキーマまたは型付きフィールドを持つログであり、下流システムが確実に解析および解釈できるものです。テキストエンコーディングは、JSON、protobuf、またはその他の形式を使用できますが、ログが構造化されているというのは、単に有効な JSON であることではなく、安定したスキーマ（フィールド名、型、意味）が存在するためです。 たとえば、構造化 JSON ログは次のようになります。
そして、インフラストラクチャーのコンポーネントには、Common Log Format（CLF） が一般的に利用されます。
ハイブリッド形式や拡張形式（たとえば、CLFフィールドと末尾のJSONデータブロックを組み合わせたもの）もあります。
そのような場合は、必要な部分を解析または抽出して正規化されたレコードに変換し、後続のツールがそれらを一貫して分析できるようにします。 OpenTelemetry コレクターの filelogreceiver はこのようにログを分析する標準化された方法が含まれています。
構造化ログは、その安定したスキーマにより、検証、解析、トレースやメトリクスとの関連付け、そして大規模な分析がしやすいため、本番環境では好まれます。
非構造化ログは一貫した構造に従わないログです。 人が読みやすい場合が多く、開発において頻繁に利用されます。 しかし、大規模な分析と解析が非常に困難なため、本番環境のオブザーバビリティの目的に対して、非構造化ログの使用は推奨されません。
本番環境において非構造化ログの蓄積と分析は可能ですが、機械が読みやすくするために大幅な分析や前処理が必要になる場合があります。 たとえば、上述した 3 つのログを解析するには、タイムスタンプを抽出するための正規表現やログメッセージの本文を一貫して抽出するためのカスタムパーサーが必要になります。 通常、ログのバックエンドがタイムスタンプを基にログを並び替えたり整理したりするには、このような処理がもとめられます。 非構造化ログを解析して分析に活用することは可能ですが、アプリケーションの標準ログフレームワークを経由して構造化ログに切り替えるよりも作業量が多くなる可能性があります。
半構造化ログとは、データを識別するために一定の一貫したパターンを使用し、機械が読みやすくしているものの、異なるシステム間でデータのフォーマットや区切り文字が統一されていないログのことを指します。例としては、キーと値のペアによるログ記録（下記参照）や、メッセージごとにフィールド名や型が異なるJSONデータなどが挙げられます。半構造化ログは非構造化ログよりも解析が容易な場合が多いですが、分析前に処理や正規化が必要となる場合もあります。
半構造化ログは、下流の分析で完全に活用するためには、データ取り込み時にマッピングと型変換が必要になる場合があります。
よくある質問として、アプリケーションコードでロギング呼び出しの前にロギングが有効かどうかをチェックすべきかというものがあります。 たとえば、次のようなコードです。
ほとんどの場合、このチェックは不要であり推奨されません。 OpenTelemetry SDK は効率的に設計されており、ロガーが有効でない場合のロギング API の呼び出しオーバーヘッドは最小限です。 logger.Enabled を追加で呼び出すと、パフォーマンスが低下し、コードが複雑になります。
Enabled API が有用なのは、ロギング呼び出しに渡す引数の評価自体にコストがかかり、ロガーが有効でないときにそのコストを避けたい場合だけです。 たとえば、本文や属性をデータベースから取得したり、高コストな操作で計算したりする必要がある場合です。
ガードする式は副作用のないものだけにしてください。 ガードされたコードはロギングが有効なときだけ実行されます。 副作用のあるコードや、他のロジックが依存するコードをガードすると、アプリケーションの動作がロギング設定に依存するようになり、微妙なバグの原因になりがちです。
また、Enabled の結果は静的ではないことに注意してください。 設定の変更に応じて結果は時間とともに変わる可能性があるため、ログレコードごとに評価すべきであり、キャッシュすべきではありません。
規範的な API ガイダンスについては、Logs API 仕様を参照してください。
以下の概念とコンポーネントのリストは、OpenTelemetry のロギングサポートを支えています。
アプリケーション開発者としては、Log Bridge API はログアペンダー/ブリッジを構築するためのロギングライブラリ作者のために提供されているので、直接呼び出すべきではありません。 かわりに、好みのロギングライブラリを使い、OpenTelemetryのログレコードエクスポーターにログを出力できるログアペンダー（またはログブリッジ）を使うように設定するだけです。
OpenTelemetry言語SDKはこの機能を提供します。
Logs Bridge APIの一部であり、ロギングライブラリの作者である場合にのみ使用すべきです。
ロガープロバイダー（ LoggerProvider と呼ばれることもある）は ロガー のファクトリーです。 ほとんどの場合、ロガープロバイダは一度初期化され、そのライフサイクルはアプリケーションのライフサイクルと一致します。 ロガープロバイダーの初期化には、リソースとエクスポーターの初期化も含まれます。
Logs Bridge APIの一部であり、ロギングライブラリの作者である場合にのみ使用すべきです。
ロガーはログレコードを作成します。ロガーはログプロバイダーから作成されます。
ログレコードエクスポーターは、ログレコードをコンシューマーに送信します。 このコンシューマーは、デバッグや開発時間用の標準出力、OpenTelemetryコレクター、あるいは、お好みのオープンソースやベンダーのバックエンドです。
ログレコードはイベントの記録を表します。 OpenTelemetryでは、ログレコードには2種類のフィールドがあります。
トップレベルのフィールドは以下の通りです。
ログレコードとログフィールドの詳細については、ログデータモデル を参照してください。
OpenTelemetryのログについての詳細は、ログ仕様 を参照してください。
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!