Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

16.2. ログハンドラーを有効にする

ログハンドラーを有効にするには、次のコマンドを入力します。 

bin/kc.[sh|bat] start --log="<handler1>,<handler2>"
Copy to Clipboard Toggle word wrap

使用可能なハンドラーは次のとおりです。

  • console
  • file
  • syslog

後述する、より具体的なハンドラー設定は、ハンドラーがこのコンマ区切りリストに追加された場合にのみ有効になります。

16.2.1. 各ハンドラーのログレベルを指定する
リンクのコピー

log-level プロパティーは、グローバルルートログレベルと選択したカテゴリーのレベルを指定します。ただし、最新のアプリケーション要件に準拠するには、ログレベルに対してよりきめ細かいアプローチが必要です。

特定のハンドラーのログレベルを設定するために、log-<handler>-level (<handler> は使用可能なログハンドラー) 形式のプロパティーが導入されました。

つまり、ログレベル設定のプロパティーは次のようになります。

  • log-console-level - コンソールログハンドラー
  • log-file-level - File ログハンドラー
  • log-syslog-level - Syslog ログハンドラー
注記

log-<handler>-level プロパティーは、特定のログハンドラーが有効になっている場合にのみ使用できます。詳細は、以下のログハンドラー設定を参照してください。

「ログレベル」 セクションで指定されたログレベルのみが受け入れられ、小文字でなければなりません。ログハンドラーの特定のカテゴリーを指定する機能はまだサポートされていません。

16.2.1.1. 一般原則
リンクのコピー

特定のハンドラーごとにログレベルを設定しても、log-level プロパティーで指定された ルートレベルはオーバーライドされない ことを理解する必要があります。ログハンドラーは、ロギングシステム全体の最大の詳細度を表すルートログレベルを考慮します。つまり、個々のログハンドラーはルートロガーよりも詳細度が低くなるように設定できますが、それ以上には設定できません。

具体的には、ハンドラーに任意のログレベルが定義されている場合、そのログレベルのログレコードが出力に存在するわけではありません。その場合、ルート log-level も評価する必要があります。ログハンドラーレベルは ルートログレベルの制限 を提供し、ログハンドラーのデフォルトのログレベルは all (制限なし) です。

16.2.1.2. 例
リンクのコピー

例: ファイルハンドラーの場合は debug、コンソールハンドラーの場合は info: 

bin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info
Copy to Clipboard Toggle word wrap

ルートログレベルは debug に設定されているため、すべてのログハンドラーはその値を継承します。File ログハンドラーも同様です。コンソールで debug レコードを非表示にするには、コンソールハンドラーの最小 (最も深刻でない) レベルを info に設定する必要があります。

例: すべてのハンドラーに対して warn、ファイルハンドラーに対しては debug: 

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug --log-console-level=warn --log-syslog-level=warn
Copy to Clipboard Toggle word wrap

ルートレベルは、最も詳細な必要なレベル (この場合は debug) に設定する必要があり、他のログハンドラーもそれに応じて修正する必要があります。

例: すべてのハンドラーの場合は info、ただし Syslog ハンドラーの場合は debug + org.keycloak.events:trace: 

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug,org.keycloak.events:trace, --log-syslog-level=trace --log-console-level=info --log-file-level=info
Copy to Clipboard Toggle word wrap

org.keycloak.events:trace を表示するには、Syslog ハンドラーの trace レベルを設定する必要があります。

16.2.2. ログハンドラーに異なる JSON 形式を使用する
リンクのコピー

すべてのログハンドラーは、JSON 形式で構造化されたログ出力機能を提供します。これは log-<handler>-output=json 形式のプロパティーによって有効にできます (<handler> はログハンドラーです)。

生成された JSON の異なる形式が必要な場合は、次の JSON 出力形式を利用できます。

  • default (デフォルト)
  • ecs

ecs 値は ECS (Elastic Common Schema) を参照します。

ECS は、Elastic ソリューションで使用される共通のフィールドセットを定義する、オープンソースのコミュニティー主導の仕様です。ECS 仕様は、OpenTelemetry によって管理される単一の標準を作成することを目標として、OpenTelemetry Semantic Conventions と統合されています。

JSON 出力形式を変更するために、log-<handler>-json-format (<handler> はログハンドラー) 形式のプロパティーが導入されました。

  • log-console-json-format - コンソールログハンドラー
  • log-file-json-format - ファイルログハンドラー
  • log-syslog-json-format - Syslog ログハンドラー

16.2.2.1. 例
リンクのコピー

コンソールログハンドラーの ECS (Elastic Common Schema) 形式の JSON ログを取得する場合は、次のコマンドを入力します。 

bin/kc.[sh|bat] start --log-console-output=json --log-console-json-format=ecs
Copy to Clipboard Toggle word wrap

ログメッセージの例

{"@timestamp":"2025-02-03T14:53:22.539484211+01:00","event.sequence":9608,"log.logger":"io.quarkus","log.level":"INFO","message":"Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 4.615s. Listening on: http://0.0.0.0:8080","process.thread.name":"main","process.thread.id":1,"mdc":{},"ndc":"","host.hostname":"host-name","process.name":"/usr/lib/jvm/jdk-21.0.3+9/bin/java","process.pid":77561,"data_stream.type":"logs","ecs.version":"1.12.2","service.environment":"prod","service.name":"Keycloak","service.version":"999.0.0-SNAPSHOT"}
Copy to Clipboard Toggle word wrap

16.2.3. 非同期ロギング
リンクのコピー

Red Hat build of Keycloak は非同期ロギングをサポートしています。これは、高スループット と 低レイテンシー が必要なデプロイメントに役立ちます。非同期ロギングは、別のスレッドを使用して、すべてのログレコードを処理します。ロギングハンドラーは、同期ロギングの場合とまったく同じように呼び出されます。Keycloak ログハンドラーのすべての Red Hat ビルドに対して非同期ロギングを有効にできます。非同期ロギングが有効になっているすべてのログハンドラーに対して専用のスレッドが作成されます。

非同期ロギングの基礎となるメカニズムは、ログレコードの処理にキューを使用します。新しいログレコードはすべてキューに追加され、非同期ロギングを有効にして特定のログハンドラーに公開されます。すべてのログハンドラーに異なるキューがあります。

キューがすでに満杯になると、メインスレッドをブロックし、キュー内の空き領域を待ちます。

16.2.3.1. 非同期ロギングを使用するタイミング
リンクのコピー

  • 受信リクエストに対する レイテンシーが低くなる
  • より高いスループットが必要です
  • ワーカースレッドプールが小さく、ロギングを個別のスレッドにオフロードしたい
  • I/O 負荷の高いログハンドラーの影響を軽減したいと考えています。
  • リモート宛先 （ネットワーク syslog サーバーなど）にロギングしており、ワーカースレッドのブロックを避けたい。
警告

非同期ロギングを有効にすると、追加の個別のスレッドと内部キューにより、メモリーのオーバーヘッド が追加される可能性があることに注意してください。この場合、リソースに制約のある環境では使用しません。さらに、サーバーが予期せぬシャットダウンを行うと、ログレコードが失わ れるリスクが発生します。

16.2.3.2. 非同期ロギングを有効にする
リンクのコピー

以下のように log-async プロパティーを使用して、すべてのログハンドラーに対して非同期ロギングをグローバルに有効にできます。 

bin/kc.[sh|bat] start --log-async=true
Copy to Clipboard Toggle word wrap

または、log-<handler> -async 形式のプロパティー(<handler> はログハンドラー )を使用して、特定の ハンドラー ごとに非同期ロギングを有効にすることもできます。特定のハンドラーのプロパティーが設定されていない場合、親の log-async プロパティーの値が使用されます。

これらのプロパティーは次のように使用できます。 

bin/kc.[sh|bat] start --log-console-async=true --log-file-async=true --log-syslog-async=true
Copy to Clipboard Toggle word wrap
  • log-console-async - Console ログハンドラー
  • log-file-async - ファイルログハンドラー
  • log-syslog-async - Syslog ログハンドラー

16.2.3.3. 変更キューの長さ
リンクのコピー

非同期ロギングに使用されるキューのサイズを変更できます。デフォルトのサイズは、キューの 512 ログレコードです。

キューの長さは次のように変更できます。 

bin/kc.[sh|bat] start --log-console-async-queue-length=512 --log-file-async-queue-length=512 --log-syslog-async-queue-length=512
Copy to Clipboard Toggle word wrap

これらのプロパティーは、これらの特定のログハンドラーで非同期ロギングが有効になっている場合にのみ利用できます。

16.2.4. HTTP アクセスロギング
リンクのコピー

Red Hat build of Keycloak は、受信 HTTP リクエストの詳細を記録する HTTP アクセスロギングをサポートします。アクセスログはデバッグやトラフィック分析によく使用されますが、セキュリティー監査やコンプライアンスの監視にも重要ですが、管理者がアクセスパターンを追跡し、疑わしいアクティビティーを特定し、監査証拠を維持するのに役立ちます。

これらのログは INFO レベルで記述されるため、ロギング設定にこのレベルが含まれるようにします（グローバル（例： log-level=info）、またはアクセスログカテゴリー（例： log-level=org.keycloak.http.access-log:info）））。HTTP アクセスログを有効にすると、INFO レベルが Red Hat ビルドの Keycloak のデフォルトのログレベルであるため、デフォルトで表示されます。

16.2.4.1. 有効にする方法
リンクのコピー

以下のように http-access-log-enabled プロパティーを使用して、HTTP アクセスログを有効にできます。 

bin/kc.[sh|bat] start --http-access-log-enabled=true
Copy to Clipboard Toggle word wrap

16.2.4.2. ログのフォーマット/パターンの変更
リンクのコピー

以下のように http-access-log-pattern プロパティーを使用すると、アクセスログレコードのフォーマット/パターンを変更できます。 

bin/kc.[sh|bat] start --http-access-log-pattern=combined
Copy to Clipboard Toggle word wrap

事前定義した名前付きパターン：

  • common （デフォルト）- 要求に関する基本情報を出力します。
  • 組み合わせ: 要求の基本情報および参照先およびユーザーエージェントに関する情報を出力します。
  • long - は、リクエストに関する包括的な情報をそのすべてのヘッダーとともに出力します

次のように、ログに記録される必要なデータを使用して独自のパターンを指定することもできます。 

bin/kc.[sh|bat] start --http-access-log-pattern='%A %{METHOD} %{REQUEST_URL} %{i,User-Agent}'
Copy to Clipboard Toggle word wrap

使用可能な変数の完全なリストは、Quarkus のドキュメント を参照してください。

16.2.4.3. 特定の URL パスを除外する
リンクのコピー

HTTP アクセスロギングから特定の URL パスを除外することができるため、記録されません。

正規表現を使用して、次のような除外できます。 

bin/kc.[sh|bat] start --http-access-log-exclude='/realms/my-internal-realm/.*'
Copy to Clipboard Toggle word wrap

この場合、/realms/my-internal-realm/ および後続のパスは HTTP アクセスログから除外されます。

トップに戻る
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2025 Red Hat