bin/kc.[sh|bat] start --log-level=<root-level>Keycloak 使用 JBoss Logging 框架。以下是可用記錄處理程式以及通用父記錄處理程式 root 的高階概述
console (主控台)
file (檔案)
syslog
Keycloak 中的記錄檔是以每個類別為基礎進行的。您可以設定根記錄層級，或是更特定的類別 (例如 org.hibernate 或 org.keycloak) 的記錄檔。也可以針對每個特定的記錄處理程式調整記錄層級。
本指南說明如何設定記錄檔。
下表定義可用的記錄層級。
| 層級 | 說明 |
|---|---|
FATAL (嚴重) |
發生嚴重失敗，完全無法處理任何類型的要求。 |
ERROR (錯誤) |
導致無法處理要求的重大錯誤或問題。 |
WARN (警告) |
可能不需要立即修正的非嚴重錯誤或問題。 |
INFO (資訊) |
Keycloak 生命週期事件或重要資訊。頻率較低。 |
DEBUG (除錯) |
用於除錯目的的更詳細資訊，例如資料庫記錄。頻率較高。 |
TRACE (追蹤) |
最詳細的除錯資訊。頻率非常高。 |
ALL (全部) |
用於所有記錄訊息的特殊層級。 |
OFF (關閉) |
用於完全關閉記錄檔的特殊層級 (不建議)。 |
如果沒有針對更特定的類別記錄器設定記錄層級，則會改用封閉的類別。如果沒有封閉的類別，則會使用根記錄器層級。
若要設定根記錄層級，請輸入下列命令
bin/kc.[sh|bat] start --log-level=<root-level>此命令使用下列準則
針對 <root-level>，提供上表定義的層級。
記錄層級不區分大小寫。例如，您可以使用 DEBUG 或 debug。
如果您不小心設定記錄層級兩次，清單中最後一次出現的記錄層級將會生效。例如，如果您包含語法 --log-level="info,…,DEBUG,…"，則根記錄器將會是 DEBUG。
您可以為 Keycloak 中的特定區域設定不同的記錄層級。使用此命令來提供您要使用不同記錄層級的類別之逗號分隔清單
bin/kc.[sh|bat] start --log-level="<root-level>,<org.category1>:<org.category1-level>"套用至類別的設定也會套用至其子類別，除非您包含更特定的相符子類別。
bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info"此範例會設定下列記錄層級
所有記錄器的根記錄層級都設定為 INFO。
一般而言，hibernate 記錄層級設定為 debug。
為了避免 SQL 抽象語法樹狀結構產生詳細的記錄輸出，特定子類別 org.hibernate.hql.internal.ast 設定為 info。因此，將會省略 SQL 抽象語法樹狀結構，而不是以 debug 層級顯示。
若要啟用記錄處理程式，請輸入下列命令
bin/kc.[sh|bat] start --log="<handler1>,<handler2>"可用的處理程式包括
console (主控台)
file (檔案)
syslog
當處理程式新增至此逗號分隔清單時，以下提及的更特定處理程式設定才會生效。
log-level 屬性會指定全域根記錄層級和選取類別的層級。不過，為了符合現代應用程式的需求，需要更精細的記錄層級方法。
若要設定特定處理程式的記錄層級，則會引入 log-<handler>-level 格式的屬性 (其中 <handler> 是可用的記錄處理程式)。
這表示記錄層級設定的屬性看起來會像這樣
log-console-level - 主控台記錄處理程式
log-file-level - 檔案記錄處理程式
log-syslog-level - Syslog 記錄處理程式
只有在啟用特定記錄處理程式時，log-<handler>-level 屬性才可用。如需更多資訊，請參閱下方的記錄處理程式設定。 |
僅接受 記錄層級 章節中指定的記錄層級，並且必須是小寫。目前不支援針對記錄處理程式指定特定類別。
必須了解為每個特定處理程式設定記錄層級不會覆寫 log-level 屬性中指定的根層級。記錄處理程式會遵守根記錄層級，這表示整個記錄系統的最大詳細程度。這表示個別記錄處理程式可以設定為比根記錄器更不詳細，但不能更詳細。
具體而言，當為處理程式定義任意記錄層級時，這並不表示具有該記錄層級的記錄會出現在輸出中。在這種情況下，也必須評估根 log-level。記錄處理程式層級會提供根記錄層級的限制，而記錄處理程式的預設記錄層級是 all - 沒有任何限制。
debug，但主控台處理程式的 infobin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info根記錄層級設定為 debug，因此每個記錄處理程式都會繼承該值，檔案記錄處理程式也是如此。若要隱藏主控台中的 debug 記錄，我們需要將主控台處理程式的最小 (最不嚴重) 層級設定為 info。
warn，但檔案處理程式的 debugbin/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:tracebin/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。
預設會啟用主控台記錄處理程式，為主控台提供非結構化記錄訊息。
Keycloak 會使用以模式為基礎的記錄格式器，預設會產生人類可讀的文字記錄。
這些行的記錄格式範本可以套用至根層級。預設格式範本為
%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n
格式字串支援下表中的符號
| 符號 | 摘要 | 說明 |
|---|---|---|
%% |
% |
轉譯簡單的 % 字元。 |
%c |
類別 |
轉譯記錄類別名稱。 |
%d{xxx} |
日期 |
以指定的日期格式字串轉譯日期。由 |
%e |
例外狀況 |
轉譯擲回的例外狀況。 |
%h |
主機名稱 |
轉譯簡單的主機名稱。 |
%H |
完整主機名稱 |
轉譯完整主機名稱，這可能會與簡單主機名稱相同，視作業系統設定而定。 |
%i |
處理序 ID |
轉譯目前的處理序 PID。 |
%m |
完整訊息 |
轉譯記錄訊息和例外狀況 (如果已擲回)。 |
%n |
換行 |
轉譯平台特定的分行符號字串。 |
%N |
處理序名稱 |
轉譯目前處理序的名稱。 |
%p |
層級 |
轉譯訊息的記錄層級。 |
%r |
相對時間 |
轉譯自應用程式記錄開始以來的時間 (以毫秒為單位)。 |
%s |
簡單訊息 |
僅轉譯記錄訊息，不包含例外狀況追蹤。 |
%t |
執行緒名稱 |
轉譯執行緒名稱。 |
%t{id} |
執行緒 ID |
轉譯執行緒 ID。 |
%z{<時區名稱>} |
時區 |
將記錄輸出的時區設定為 <時區名稱>。 |
%L |
行號 |
轉譯記錄訊息的行號。 |
若要設定記錄行的記錄格式，請執行下列步驟
使用上表建立您想要的格式範本。
輸入下列命令
bin/kc.[sh|bat] start --log-console-format="'<format>'"請注意，當使用 CLI 叫用包含特殊 Shell 字元 (例如 ;) 的命令時，您需要逸出字元。因此，請考慮改在組態檔案中進行設定。
bin/kc.[sh|bat] start --log-console-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"此範例會將類別名稱縮寫為三個字元，方法是在範本中設定 [%c{3.}]，而不是預設的 [%c]。
根據預設，主控台記錄處理程式會將純文字非結構化資料記錄到主控台。若要改用結構化 JSON 記錄輸出，請輸入下列命令
bin/kc.[sh|bat] start --log-console-output=json{"timestamp":"2022-02-25T10:31:32.452+01:00","sequence":8442,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.253s. Listening on: http://0.0.0.0:8080","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host-name","processName":"QuarkusEntryPoint","processId":36946}使用 JSON 輸出時，會停用色彩，且 --log-console-format 設定的格式設定將不會套用。
若要使用非結構化記錄，請輸入下列命令
bin/kc.[sh|bat] start --log-console-output=default2022-03-02 10:36:50,603 INFO [io.quarkus] (main) Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.615s. Listening on: http://0.0.0.0:8080預設會停用非結構化記錄的彩色主控台記錄輸出。色彩可以改善可讀性，但當將記錄傳送到外部記錄彙總系統時，可能會造成問題。若要啟用或停用色彩編碼的主控台記錄輸出，請輸入下列命令
bin/kc.[sh|bat] start --log-console-color=<false|true>可以使用 --log-console-level 屬性指定主控台記錄處理程式的記錄層級，如下所示
bin/kc.[sh|bat] start --log-console-level=warn如需更多資訊，請參閱上方 指定每個處理程式的記錄層級 章節。
除了記錄到主控台之外，您也可以使用非結構化記錄記錄到檔案。
預設會停用記錄到檔案。若要啟用它，請輸入下列命令
bin/kc.[sh|bat] start --log="console,file"名為 keycloak.log 的記錄檔會在 Keycloak 安裝的 data/log 目錄內建立。
若要變更記錄檔的建立位置和檔案名稱，請執行下列步驟
建立可寫入的目錄以儲存記錄檔。
如果目錄不可寫入，Keycloak 會正確啟動，但會發出錯誤訊息，且不會建立任何記錄檔。
輸入此命令
bin/kc.[sh|bat] start --log="console,file" --log-file=<path-to>/<your-file.log>若要為檔案記錄處理器設定不同的記錄格式，請輸入以下命令
bin/kc.[sh|bat] start --log-file-format="<pattern>"請參閱設定主控台記錄格式，以取得更多資訊和可用模式設定的表格。
檔案記錄處理器的記錄層級可以使用 --log-file-level 屬性指定，如下所示
bin/kc.[sh|bat] start --log-file-level=warn如需更多資訊，請參閱上方 指定每個處理程式的記錄層級 章節。
Keycloak 提供將記錄傳送至遠端 Syslog 伺服器的功能。它使用 RFC 5424 中定義的協定。
若要啟用使用 Syslog 的記錄功能，請將其新增至已啟用的記錄處理器清單，如下所示
bin/kc.[sh|bat] start --log="console,syslog"若要設定不同的應用程式名稱，請新增 --log-syslog-app-name 選項，如下所示
bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-app-name=kc-p-itadmins如果未設定，應用程式名稱預設為 keycloak。
若要設定集中記錄系統的端點（主機:連接埠），請輸入以下命令，並將值替換為您的特定值
bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-endpoint=myhost:12345當啟用 Syslog 處理器時，主機會使用 localhost 作為主機值。預設連接埠為 514。
Syslog 記錄處理器的記錄層級可以使用 --log-syslog-level 屬性指定，如下所示
bin/kc.[sh|bat] start --log-syslog-level=warn如需更多資訊，請參閱上方 指定每個處理程式的記錄層級 章節。
Syslog 預設使用 TCP 作為通訊協定。若要改用 UDP 而非 TCP，請新增 --log-syslog-protocol 選項，如下所示
bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-protocol=udp可用的協定有：tcp、udp 和 ssl-tcp。
若要設定記錄行的記錄格式，請執行下列步驟
使用上表建立您想要的格式範本。
輸入下列命令
bin/kc.[sh|bat] start --log-syslog-format="'<format>'"請注意，當使用 CLI 叫用包含特殊 Shell 字元 (例如 ;) 的命令時，您需要逸出字元。因此，請考慮改在組態檔案中進行設定。
bin/kc.[sh|bat] start --log-syslog-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"此範例會將類別名稱縮寫為三個字元，方法是在範本中設定 [%c{3.}]，而不是預設的 [%c]。
Syslog 會根據特定的 RFC 規格使用不同的訊息格式。若要使用不同的訊息格式變更 Syslog 類型，請使用 --log-syslog-type 選項，如下所示
bin/kc.[sh|bat] start --log-syslog-type=rfc3164--log-syslog-type 選項的可能值為
rfc5424（預設）
rfc3164
若要設定允許傳送的訊息最大長度（以位元組為單位），請使用 --log-syslog-max-length 選項，如下所示
bin/kc.[sh|bat] start --log-syslog-max-length=1536長度可以使用適當的後綴以記憶體大小格式指定，例如 1k 或 1K。長度包含標頭和訊息。
如果未明確設定長度，則會根據 --log-syslog-type 選項設定預設值，如下所示
2048B - 用於 RFC 5424
1024B - 用於 RFC 3164
預設情況下，Syslog 記錄處理器會將純粹非結構化資料傳送至 Syslog 伺服器。若要改用結構化 JSON 記錄輸出，請輸入以下命令
bin/kc.[sh|bat] start --log-syslog-output=json2024-04-05T12:32:20.616+02:00 host keycloak 2788276 io.quarkus - {"timestamp":"2024-04-05T12:32:20.616208533+02:00","sequence":9948,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Profile prod activated. ","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host","processName":"QuarkusEntryPoint","processId":2788276}當使用 JSON 輸出時，色彩會停用，且 --log-syslog-format 設定的格式設定將不會套用。
若要使用非結構化記錄，請輸入下列命令
bin/kc.[sh|bat] start --log-syslog-output=default2024-04-05T12:31:38.473+02:00 host keycloak 2787568 io.quarkus - 2024-04-05 12:31:38,473 INFO [io.quarkus] (main) Profile prod activated.如您所見，時間戳記出現兩次，因此您可以透過 --log-syslog-format 屬性相應地修改它。
| 值 | |
|---|---|
|
|
僅在啟用主控台記錄處理器時可用 |
|
僅在啟用主控台記錄處理器時可用 |
（預設） |
僅在啟用主控台記錄處理器和追蹤時可用 |
|
僅在啟用主控台記錄處理器時可用 |
|
僅在啟用主控台記錄處理器時可用 |
|
僅在啟用檔案記錄處理器時可用 |
（預設） |
僅在啟用檔案記錄處理器時可用 |
（預設） |
僅在啟用檔案記錄處理器和追蹤時可用 |
|
僅在啟用檔案記錄處理器時可用 |
|
僅在啟用檔案記錄處理器時可用 |
|
|
（預設） |
僅在啟用 Syslog 時可用 |
（預設） |
僅在啟用 Syslog 時可用 |
（預設） |
僅在啟用 Syslog 時可用 |
（預設） |
僅在啟用 Syslog 處理器和追蹤時可用 |
|
僅在啟用 Syslog 時可用 |
|
僅在啟用 Syslog 時可用 |
|
僅在啟用 Syslog 時可用 |
|
僅在啟用 Syslog 時可用 |
|
僅在啟用 Syslog 時可用 |
|