Logcat 指令列工具

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 的指令列選項：

adb logcat -t '01-26 20:52:41.820'

adb logcat -t '01-26 20:52:41.820'

adb logcat -p

$ adb logcat -P '"<allowlist_and_denylist>"'

or

adb shell
$ logcat -P '<allowlist_and_denylist>'

adb logcat -P '"/32676 675 ~/32677 897"'

~! worst uid denylist
~1000/! worst pid in system (1000)

篩選記錄輸出

記錄訊息的標記是一簡短字串，指出訊息的來源系統元件。例如，檢視系統的「View」。

優先順序是下列字元代表的其中一層意義，由低至高排序：

如要獲得系統內使用、一併附上優先度的標記清單，請執行 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) (錯誤)

以下列呼叫模式為例：

Log.i("MyActivity", "MyClass.getView() — get item number $position")

Log.i("MyActivity", "MyClass.getView() — get item number " + position);

logcat 輸出的內容如以下所示：

I/MyActivity( 1557): MyClass.getView() — get item number 1