Red Hat Summit16.2. ログハンドラーを有効にする
ログハンドラーを有効にするには、次のコマンドを入力します。
bin/kc.[sh|bat] start --log="<handler1>,<handler2>"
bin/kc.[sh|bat] start --log="<handler1>,<handler2>"使用可能なハンドラーは次のとおりです。
-
console -
file -
syslog
後述する、より具体的なハンドラー設定は、ハンドラーがこのコンマ区切りリストに追加された場合にのみ有効になります。
16.2.1. 各ハンドラーのログレベルを指定する
log-level プロパティーは、グローバルルートログレベルと選択したカテゴリーのレベルを指定します。ただし、最新のアプリケーション要件に準拠するには、ログレベルに対してよりきめ細かいアプローチが必要です。
特定のハンドラーのログレベルを設定するために、log-<handler>-level (<handler> は使用可能なログハンドラー) 形式のプロパティーが導入されました。
つまり、ログレベル設定のプロパティーは次のようになります。
-
log-console-level- Console ログハンドラー -
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
bin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info
ルートログレベルは 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
bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug --log-console-level=warn --log-syslog-level=warn
ルートレベルは、最も詳細な必要なレベル (この場合は 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
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
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- Console ログハンドラー -
log-file-json-format- File ログハンドラー -
log-syslog-json-format- Syslog ログハンドラー
16.2.2.1. 例
Console ログハンドラーの ECS (Elastic Common Schema) 形式の JSON ログを取得する場合は、次のコマンドを入力します。
bin/kc.[sh|bat] start --log-console-output=json --log-console-json-format=ecs
bin/kc.[sh|bat] start --log-console-output=json --log-console-json-format=ecsログメッセージの例
{"@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"}
{"@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"}16.2.3. 非同期ロギング
Red Hat build of Keycloak は非同期ロギングをサポートしており、高スループット と 低レイテンシー を必要とするデプロイメントに役立つ可能性があります。非同期ロギングは、すべてのログレコードの処理を別のスレッドを使用して行います。ロギングハンドラーは、同期ロギングとまったく同じ方法で呼び出されますが、別々のスレッドで実行されます。すべての Red Hat build of Keycloak ログハンドラーに対して非同期ロギングを有効化できます。非同期ロギングが有効化されているログハンドラーごとに、専用のスレッドが作成されます。
非同期ロギングの基礎となるメカニズムでは、ログレコードを処理するためにキューが使用されます。すべての新しいログレコードはキューに追加され、非同期ロギングが有効になっている特定のログハンドラーに公開されます。ログハンドラーごとにキューが異なります。
キューがすでにいっぱいの場合は、メインスレッドをブロックし、キューの空き領域を待機します。
16.2.3.1. 非同期ロギングを使用するタイミング
- 受信リクエストの レイテンシーを低くする 必要がある場合
- より高いスループット が必要な場合
- ワーカースレッドプールが小さく、ロギングを別のスレッドにオフロードしたい場合
- I/O 負荷の高いログハンドラー の影響を軽減したい場合
- リモートの宛先 (ネットワーク syslog サーバーなど) にロギングしており、ワーカースレッドのブロックを回避したい場合
非同期ロギングを有効にすると、追加の別個のスレッドと内部キューにより、追加のメモリーオーバーヘッド が発生する可能性があることに注意してください。その場合、リソースが制限された環境での使用は推奨しません。さらに、予期しないサーバーのシャットダウンにより、ログレコードが失われる リスクが生じます。
16.2.3.2. 非同期ロギングを有効にする
次のように log-async プロパティーを使用して、すべてのログハンドラーに対して非同期ロギングをグローバルに有効化できます。
bin/kc.[sh|bat] start --log-async=true
bin/kc.[sh|bat] start --log-async=true
または、log-<handler>-async (<handler> はログハンドラー) の形式のプロパティーを使用して、特定のハンドラーごとに非同期ロギングを有効化することもできます。特定のハンドラーのプロパティーが設定されていない場合は、親の log-async プロパティーの値が使用されます。
これらのプロパティーは次のように使用できます。
bin/kc.[sh|bat] start --log-console-async=true --log-file-async=true --log-syslog-async=true
bin/kc.[sh|bat] start --log-console-async=true --log-file-async=true --log-syslog-async=true-
log-console-async- Console ログハンドラー -
log-file-async- File ログハンドラー -
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
bin/kc.[sh|bat] start --log-console-async-queue-length=512 --log-file-async-queue-length=512 --log-syslog-async-queue-length=512これらのプロパティーは、これらの特定のログハンドラーに対して非同期ロギングが有効になっている場合にのみ使用可能です。
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 build of Keycloak のデフォルトのログレベルであるため、デフォルトで表示されます。
16.2.4.1. 有効化の方法
次のように http-access-log-enabled プロパティーを使用して、HTTP アクセスロギングを有効化できます。
bin/kc.[sh|bat] start --http-access-log-enabled=true
bin/kc.[sh|bat] start --http-access-log-enabled=true16.2.4.2. 変更ログの形式/パターン
次のように http-access-log-pattern プロパティーを使用して、アクセスログレコードの形式/パターンを変更できます。
bin/kc.[sh|bat] start --http-access-log-pattern=combined
bin/kc.[sh|bat] start --http-access-log-pattern=combined定義済みの名前付きパターン:
-
common(デフォルト) - 要求に関する基本情報を出力します -
combined- 要求に関する基本情報とリファラーおよびユーザーエージェントに関する情報を出力します -
long- 要求に関する包括的な情報をすべてのヘッダーとともに出力します
次のように、ログ記録する必要なデータを使用して独自のパターンを指定することもできます。
bin/kc.[sh|bat] start --http-access-log-pattern='%A %{METHOD} %{REQUEST_URL} %{i,User-Agent}'
bin/kc.[sh|bat] start --http-access-log-pattern='%A %{METHOD} %{REQUEST_URL} %{i,User-Agent}'
HTTP アクセスログには、認可、Cookie、外部 API キー参照などの機密性の高い HTTP ヘッダーが含まれる場合があります。長い パターンを使用したり、ヘッダーをカスタム形式で出力したりする場合は、開発目的でのみ使用してください。
使用できる変数の完全なリストは、Quarkus のドキュメント を参照してください。
16.2.4.3. 特定の URL パスを除外する
特定の URL パスを HTTP アクセスロギングから除外して、記録されないようにすることができます。
次のように、正規表現を使用して除外することができます。
bin/kc.[sh|bat] start --http-access-log-exclude='/realms/my-internal-realm/.*'
bin/kc.[sh|bat] start --http-access-log-exclude='/realms/my-internal-realm/.*'
この場合、/realms/my-internal-realm/ および後続のパスへのすべての呼び出しは、HTTP アクセスログから除外されます。
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}