Logcat 是一種指令列工具,會在裝置擲回錯誤時轉儲系統訊息記錄,並使用 Log
類別傳送您從應用程式寫入的訊息。
本頁面主要說明指令列 logcat
工具,但您其實也可以在 Android Studio 的「Logcat」視窗中檢視訊息記錄。如要瞭解如何從 Android Studio 檢視及篩選記錄,請參閱使用 Logcat 檢視及寫入記錄。
記錄系統總覽
Android 記錄系統是一組由系統程序 logd
維護的環形緩衝區結構。這組緩衝區結構受到系統規範,十分穩定。最相關的緩衝區如下:
main
:儲存大部分應用程式記錄。system
:儲存來自 Android OS 的訊息。-
crash
:儲存當機記錄。每次記錄都有優先順序、識別記錄來源的標記,以及實際的記錄訊息。
記錄系統的主要介面是共用資料庫 liblog
和其標頭 <android/log.h>
。
所有語言專用的記錄設備最終都會呼叫 __android_log_write
函式。根據預設會呼叫 __android_log_logd_logger
函式,並利用通訊端將記錄傳送至 logd
。從 API 層級 30 開始,可以透過呼叫 __android_set_log_writer
來變更記錄函式。詳情請參閱NDK 說明文件。
adb logcat
顯示的記錄會經過四次不同等級的篩選:
- 編譯時間篩選
- 視編譯設定而定,部分記錄可能會從二進位檔完全移除。例如,您可以設定 ProGuard 來移除 Java 程式碼中對
Log.d
的呼叫記錄。 - 系統屬性篩選
liblog
會查詢一組系統屬性,來決定需要傳送到logd
的最小嚴重性等級。如果您的記錄中包含MyApp
標記,則系統會檢查以下屬性,並且記錄須包含最低嚴重性的第一個字母 (V
、D
、I
、W
、E
,若程度嚴重到S
將停用所有記錄):log.tag.MyApp
persist.log.tag.MyApp
log.tag
persist.log.tag
- 應用程式篩選
- 如未設定任何屬性,
liblog
會使用__android_log_set_minimum_priority
設定的最小優先順序。預設為INFO
。 - 顯示器篩選
adb logcat
支援額外的篩選器,可減少logd
顯示的記錄量。詳情請參閱篩選記錄輸出一節。
指令列語法
如要透過 adb
殼層執行 logcat
,一般用途為:
[adb] logcat [<option>] ... [<filter-spec>] ...
您可以將 logcat
當做 adb
指令執行,也可以直接在模擬器或已連結的裝置中的殼層提示中運作。想用 adb
檢視記錄輸出內容,請前往 SDK platform-tools/
目錄並執行下列指令:
adb logcat
如想取得 logcat
線上說明,請啟動裝置並執行下列指令:
adb logcat --help
建立裝置的殼層連線並執行下列指令:
$ adb shell # logcat
選項
下表將說明 logcat
的指令列選項:
選項 | 說明 |
---|---|
-b <buffer> |
載入備用記錄緩衝區來檢視,例如 events 或 radio 。根據預設,系統會使用 main 、system 和 crash 緩衝區組合。請參閱檢視備用記錄緩衝區一節。
|
-c, --clear |
清除所選的緩衝區並結束。預設緩衝區組合為 main 、system 和 crash 。如要清除所有緩衝區,請使用 -b all -c 。
|
|
僅顯示當 <expr> 為一規則運算式,且記錄訊息與 <expr> 相符的記錄。 |
|
在顯示 <count> 行後結束。本設計為與 --regex 配對,但也會自行運作。 |
--print |
可 --regex 和 --max-count 配對使用,讓內容略過規則運算式篩選器,但仍會在達到正確的比對數時停止。 |
-d |
讓記錄轉儲在畫面上後退出。 |
-f <filename> |
將記錄訊息輸出寫入 <filename> 。預設為 stdout 。 |
-g, --buffer-size |
顯示指定記錄緩衝區的大小後退出。 |
-n <count> |
將輪替的記錄數量上限寫入 <count> 。預設值為 4。需要有 -r 選項。 |
-r <kbytes> |
每輸出 <kbytes> 一次,輪替一次記錄檔。預設值為 16。需要有 -f 選項。 |
-s |
等同於篩選運算式 '*:S' ,能為所有標記設定靜音優先順序,並用來優先篩選出新增內容的運算式清單。詳情請參閱篩選記錄輸出一節。
|
-v <format> |
設定記錄訊息的輸出格式。預設值為 threadtime 格式。
如需支援格式的清單,請參閱控制記錄輸出格式一節。
|
-D, --dividers |
顯示每個記錄緩衝區之間的分隔符號。 |
-c |
清除所有記錄並結束。 |
-t <count> |
僅顯示時間最近的數行。這個選項包含 -d 功能。 |
-t '<time>' |
顯示指定時間之後的最新數行。這個選項包含 -d 功能。如要瞭解含有內嵌空格的參數引用,請參閱-P 選項部分。
adb logcat -t '01-26 20:52:41.820' |
-T <count> |
顯示指定時間之後的最新數行。這個選項不包括 -d 功能。 |
-T '<time>' |
顯示指定時間之後的最新數行。這個選項不包括 -d 功能。如要瞭解含有內嵌空格的參數引用,請參閱 -P 選項部分。
adb logcat -t '01-26 20:52:41.820' |
-L, --last |
轉儲上次重新啟動之前的記錄。 |
-B, --binary |
以二進位檔案輸出記錄。 |
-S, --statistics |
在輸出結果中加入統計資料,以便您辨識並鎖定垃圾記錄發布者。 |
-G <size> |
設定記錄環形緩衝區的大小。在結尾加上 K 或 M 來表示 KB 或 MB。 |
-p, --prune |
顯示許可清單和拒絕清單,且不需要引數,如下所示:
adb logcat -p |
-P '<list> ...'
|
寫入許可清單和拒絕清單,以便針對特定用途調整記錄內容。您提供許可清單和拒絕清單資料的複合型內容,且 <allowlist> 或 <denylist> 可為 UID、UID/PID 或 PID。參考 logcat 統計資料 (logcat -S ) 的指南,就可以考慮針對不同目的調整許可清單和拒絕清單,例如:
根據預設,記錄系統會經常性自動避開記錄數據中行為最嚴重的違規者,以騰出空間存放新的記錄訊息。耗盡了所有的經驗法則後,系統會裁掉最舊的項目以騰出空間存放新訊息。 當您的 Android 識別編號 (AID) 成為程序 AID 和 GID 時,新增許可清單可避免它被當成犯罪者。新增拒絕清單可以幫助您釋出空間,再判斷出行為最嚴重的違規者。您可以自行設定裁舊的運作頻率。也可以適時關閉裁舊功能,讓系統僅移除每個記錄緩衝區中最老舊的內容。 引用
$ adb logcat -P '"<allowlist_and_denylist>"' or adb shell $ logcat -P '<allowlist_and_denylist>' 以下範例指定有 PID 32676 和 UID 675 的許可清單,以及有 PID 32677 和 UID 897 的拒絕清單。拒絕清單上的 PID 32677 將被賦予權重,以加快裁舊作業。 adb logcat -P '"/32676 675 ~/32677 897"' 您可以使用下列許可清單和拒絕指令變化版本: ~! worst uid denylist ~1000/! worst pid in system (1000) |
--pid=<pid> ... |
僅顯示指定 PID 的記錄。 |
--uid=<uids> ... |
只顯示半形逗號分隔清單 <uids> 中的 UID 記錄訊息。未執行任何名稱查詢,因此必須提供 UID 做為數值。這個選項僅適用於「根」、「記錄」和「系統」使用者,因為只有這些使用者才能檢視其他使用者的記錄。
|
--wrap |
休眠 2 小時後,或緩衝即將結束時 (兩者取其先)。採用緩衝結束前的自動喚醒機制,來提升輪詢效率。 |
篩選記錄輸出
記錄訊息的標記是一簡短字串,指出訊息的來源系統元件。例如,檢視系統的「View」。
優先順序是下列字元代表的其中一層意義,由低至高排序:
V
:詳細 (優先度最低)D
:偵錯I
:資訊W
:警示E
:錯誤F
:嚴重S
:靜音 (優先度最高,不顯示任何記錄)
如要獲得系統內使用、一併附上優先度的標記清單,請執行 logcat
並觀察每則訊息的前兩欄,顯示如 <priority>/<tag>
。
以下是使用 logcat -v brief output
指令取得的 logcat
輸出內容簡短範例。輸出結果顯示訊息與優先等級「I」和「ActivityManager」標記有關:
I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}
想將記錄輸出量縮減至可管理的程度,請使用「篩選運算式」來限制記錄輸出。您可以透過篩選運算式,向系統指出想關注的標記/優先度組合。系統將會專注於選定的標記而隱藏其他訊息。
篩選運算式符合以下格式:tag:priority ...
。其中 tag
代表重點標記;priority
,則是針對該標記需要呈報的最低優先度。系統會將屬於該標記、且優先度在設定值以上的訊息寫入記錄檔。在單一篩選運算式中提供任意數量的 tag:priority
規格。這些設定值之間設有空格來分隔。
以下範例呈現的是,篩選運算式隱藏了除以下兩種情況外的所有訊息記錄:附有「ActivityManager」標記、且優先度為「Info」以上,或附有「MyApp」標記、且優先度為「Debug」以上:
adb logcat ActivityManager:I MyApp:D *:S
上述運算式中的最後一個元素 *:S
會將所有標記的優先度設為「靜音」,來確保系統只會顯示含有「ActivityManager」和「MyApp」標記的訊息記錄。使用 *:S
可確保記錄輸出內容侷限於您明確指定的篩選器。*:S
能讓您的篩選器做為記錄輸出的許可清單。
注意:在部分殼層中,「*
」字元是由殼層保留。如果您要使用這類殼層,請在篩選器運算式前後加上引號:adb logcat
"ActivityManager:I MyApp:D *:S"
以下篩選運算式會顯示所有標記內,優先度為「warning」以上的記錄訊息:
adb logcat *:W
如果您正從開發電腦,而非遠端 adb
殼層執行 logcat
,也可以匯出環境變數 ANDROID_LOG_TAGS
的值,藉此設定預設的篩選運算式:
export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"
如果您是透過遠端殼層或使用 adb shell
logcat
來執行 logcat
,則 ANDROID_LOG_TAGS
篩選器不會匯出至模擬器/裝置執行個體。
控制記錄輸出格式
記錄訊息除了標記和優先度之外,還附有多個中繼資料欄位。您可以修改訊息的輸出格式,讓訊息顯示特定的中繼資料欄位。方法是使用 -v
選項,並指定下列其中一種支援的輸出格式:
brief
:顯示優先度、標記,和發布該訊息的程序 ID (PID)。long
:顯示所有中繼資料欄位,並以空白行隔開不同訊息。process
:僅顯示 PID。raw
:顯示不含其他中繼資料欄位的原始記錄訊息。tag
:僅顯示優先度和標記。thread:
為一舊版格式,會顯示優先度、PID,以及發布該訊息的執行緒 ID (TID)。threadtime
(預設):顯示訊息的傳送日期、叫用時間、優先度、標記、PID,以及發布該訊息的執行緒 ID (TID)。time
:顯示訊息的傳送日期、叫用時間、優先度、標記,以及發布該訊息的程序 ID (PID)。
啟動 logcat
時,請使用 -v
選項指定需要的輸出格式:
[adb] logcat [-v <format>]
以下範例將呈現如何產生 thread
輸出格式的訊息:
adb logcat -v thread
您只能使用 -v
選項指定一種輸出格式。不過,您也可以視需要指定任意數量的合適修飾符。logcat
會忽略不合適的修飾符。
格式修飾符
格式修飾符會變更 logcat
輸出內容。如要指定格式修飾符,請使用 -v
選項,如下所示:
adb logcat -b all -v color -d
每一則 Android 記錄訊息都有相關的標記和優先順序。 任何格式修飾符皆可與下列任一格式選項搭配使用:
brief
long
process
raw
tag
thread
threadtime
time
如要設定下列修飾符的詳細資料格式,請在指令列中輸入 logcat -v --help
:
color
:以不同顏色表示不同優先度。descriptive
:顯示記錄緩衝區的事件說明。這項修飾符只會影響事件記錄緩衝區的訊息,並不影響其他非二進位緩衝區。事件說明取自事件、記錄和標記的集合資料庫。epoch
:顯示從 1970 年 1 月 1 日開始至今的時間 (以秒為單位)。monotonic
:顯示從上次啟動以來,CPU 的總運作時間 (以秒為單位)。printable
:確保所有二進位檔記錄內容均成功逸出。uid
:如果存取控制允許,顯示已記錄程序的 UID 或 Android ID。usec
:顯示時間 (單位精確到微秒)。UTC
:顯示世界協調時間。year
:於顯示時間中加入年份。zone
:於顯示時間中加入當地時區。
檢視備用記錄緩衝區
Android 記錄系統會保留多個環形緩衝區來存放記錄訊息,但也並非所有記錄訊息都會傳送至預設的環形緩衝區。想查看其他記錄訊息,您可以使用 -b
選項來執行 logcat
指令,請求檢視備用環形緩衝區。您可以檢視下列任一備用緩衝區:
radio
:檢視內含無線電/電話服務相關訊息的緩衝區。events
:檢視已解譯的二進位系統事件緩衝區訊息。main
:檢視主要記錄緩衝區 (預設),不含系統和當機記錄訊息。system
:檢視系統記錄緩衝區 (預設)。crash
:檢視系統當機記錄緩衝區 (預設)。all
:檢視所有緩衝區。default
:回報main
、system
,和crash
緩衝區。
-b
的使用方式為:
[adb] logcat [-b <buffer>]
以下範例說明如何檢視包含無線電和電話服務訊息的記錄緩衝區:
adb logcat -b radio
如要為您想要顯示的所有緩衝區指定多個 -b
旗標,請輸入以下內容:
logcat -b main -b radio -b events
針對半形逗號分隔的緩衝區清單指定一 -b
旗標,例如:
logcat -b main,radio,events
程式碼記錄
Log
類別可讓您在程式碼中建立 logcat
工具中顯示的記錄項目。常見的記錄方式包括:
Log.v(String, String)
(詳細資訊)Log.d(String, String)
(偵錯)Log.i(String, String)
(資訊)Log.w(String, String)
(警示)Log.e(String, String)
(錯誤)
以下列呼叫模式為例:
Kotlin
Log.i("MyActivity", "MyClass.getView() — get item number $position")
Java
Log.i("MyActivity", "MyClass.getView() — get item number " + position);
logcat
輸出的內容如以下所示:
I/MyActivity( 1557): MyClass.getView() — get item number 1