Google は、黒人コミュニティに対する人種平等の促進に取り組んでいます。取り組みを見る

logcat コマンドライン ツール

logcat は、デバイスがエラーをスローしたときのスタック トレースや、Log クラスを使用してアプリから書き込んだメッセージといった、システム メッセージのログをダンプするコマンドライン ツールです。

このページでは、logcat コマンドライン ツールについて説明します。ログメッセージは、Android Studio の [Logcat] ウィンドウから表示することもできます。Android Studio からログの表示やフィルタリングを行う方法については、logcat を使用してログを書き込み、表示するをご覧ください。

ログシステムの概要

Android のログシステムは、システム プロセス logd によって管理される構造化されたサークル バッファのセットです。使用可能なバッファセットは、システムによって固定および定義されます。最も重要なバッファセットは、main(ほとんどのアプリケーション ログを格納)、system(Android OS によって生成されたメッセージを格納)、crash(クラッシュログを格納)です。各ログエントリは、優先度(VERBOSEDEBUGINFOWARNINGERRORFATAL のいずれか)、ログの生成元を特定するタグ、実際のログメッセージで構成されます。

ログシステムへのプライマリ インターフェースは、共有ライブラリ liblog とそのヘッダーの <android/log.h> です。言語固有のすべてのログ機能は、最終的に関数 __android_log_write を呼び出します。この関数はデフォルトで、ソケットを使用してログエントリを logd に送信する関数 __android_log_logd_logger を呼び出します。API レベル 30 以降では、__android_set_log_writer を呼び出すことによってこのログ関数を変更できます。詳しくは、NDK のドキュメントをご覧ください。

adb logcat で表示されるログには次の 4 つのレベルのフィルタリングが行われます。

  1. コンパイル時のフィルタリング: コンパイルの設定によっては、一部のログがバイナリから完全に削除されることがあります。たとえば、Log.d の呼び出しを Java コードから削除するように Proguard を設定できます。
  2. システム プロパティのフィルタリング: liblog が一連のシステム プロパティを照会し、logd に送信する最小優先度レベルを決定します。ログにタグ MyApp が付与されている場合、以下のプロパティがチェックされます。これらのプロパティには、最小優先度の最初の文字(VDIWE、またはすべてのログを無効にする S)が含まれている必要があります。
    • log.tag.MyApp
    • persist.log.tag.MyApp
    • log.tag
    • persist.log.tag
  3. アプリケーションのフィルタリング: どのプロパティも設定されていない場合、liblog__android_log_set_minimum_priority によって設定された最小優先度を使用します。デフォルトの設定は INFO です。
  4. 表示のフィルタリング: 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> eventsradio など、表示する代替ログバッファを読み込みます。デフォルトでは、mainsystemcrash のバッファセットが使用されます。代替ログバッファを表示するをご覧ください。
-c, --clear 選択したバッファをクリア(フラッシュ)して終了します。デフォルトのバッファセットは、mainsystemcrash です。すべてのバッファをクリアするには、-b all -c を使用します。
-e <expr>, --regex=<expr> ログメッセージが <expr> に一致した行に限り出力します(<expr> は正規表現)。
-m <count>, --max-count=<count> <count> の行数を出力した後に終了します。このオプションは、--regex と併用することが想定されていますが、単独でも機能します。
--print --regex および --max-count と併用することで、コンテンツは regex フィルタをバイパスするようになりますが、適切な一致数に達した時点で停止します。
-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 を追加するとメガバイト単位で指定できます。
-p, --prune 現在の許可(white)リストと拒否(black)リストを出力します(読み取ります)。下記のように、引数は取りません。

adb logcat -p
-P '<list> ...'
--prune '<list> ...' -P '<white_and_black_list>'
許可(white)リストと拒否(black)リストを書き込んで(設定して)、特定の目的に合わせてログコンテンツを調整します。許可(<white>)リストと拒否(~<black>)リストのエントリを組み合わせて指定します。<white><black> は、UID、UID/PID、/PID のいずれかです。logcat 統計情報(logcat -S)に基づいて、以下のような目的に応じて許可(white)リストと拒否(black)リストを調整します。
  • UID を選択することで、特定のログコンテンツに最長の寿命を付与します。
  • ユーザー(UID)やプロセス(PID)によるこうしたリソースの消費を阻止することで、ログの寿命を延ばし、診断対象の問題を詳細に把握できるようにします。

ログシステムはデフォルトで、ログ統計情報内で最も邪魔なエントリを自動的に阻止して、新しいログメッセージのスペースを動的に確保します。このヒューリスティックの適用が完了すると、システムは、最も古いエントリをプルーニングして、新しいメッセージのスペースを確保します。

許可リスト(whitelist)を追加すると、Android ID 番号(AID)が保護され、プロセスの AID と GID が「邪魔な ID」として宣言されることがなくなります。拒否リストを追加すると、最も邪魔なエントリを判断する前に、スペースを解放できます。プルーニングのレベルは選択可能です。また、プルーニングをオフにすると、各ログバッファの中で最も古いエントリのコンテンツだけを削除するように指定できます。

引用符

adb logcat は引用符を保持しないため、許可リスト(white)と拒否(black)のリストを指定する構文は次のようになります。


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

or

adb shell
$ logcat -P '<white_and_blacklist>'

PID 32676 と UID 675 を許可(white)リストに登録し、PID 32677 と UID 897 を拒否(black)リストに登録する例を以下に示します。拒否リストの PID 32677 は、早くプルーニングするために重み付けされています。


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

ほかにも、次のような許可(white)リストと拒否(black)リストのコマンド バリエーションを利用できます。


~! worst uid blacklist
~1000/! worst pid in system (1000)
--pid=<pid> ... 指定した PID からのログだけを出力します。
--wrap 2 時間が経過したときか、バッファがラップを開始しようとしたときのいずれか早いほうでスリープします。ラップ開始時ウェイクアップを指定することで、ポーリングの効率を改善できます。

ログ出力をフィルタリングする

  • ログメッセージのタグは、メッセージの送信元のシステム コンポーネントを示す短い文字列です(たとえば、ビューシステムの場合は「View」)。
  • 優先度は、以下のいずれかの文字値になります(優先度が低い順)。
    • V: Verbose(最も低い優先度)
    • D: Debug
    • I: Info
    • W: Warning
    • E: Error
    • F: Fatal
    • S: Silent(最も高い優先度。何も出力されません)

logcat を実行して、各メッセージの最初の 2 つの列(<priority>/<tag>)を見ると、システム内で使用されるタグと優先度のリストを確認できます。

logcat -v brief output コマンドで取得した簡潔な logcat 出力の例を以下に示します。メッセージに対して、優先度レベル「I」とタグ「ActivityManager」が指定されています。

I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}

管理可能なレベルまでログ出力を減らすには、フィルタ式を使用してログ出力を制限します。フィルタ式を使用すると、対象となるタグと優先度の組み合わせをシステムに示すことができます。これにより、指定したタグが付いたメッセージのみが表示されるようになります。

フィルタ式は、tag:priority ... という形式になります。tag は対象のタグを示し、priority はそのタグをレポートする最小レベルの優先度を示しています。そのタグが付いたメッセージのうち、指定した優先度以上のメッセージがログに書き込まれます。1 つのフィルタ式で任意の数の tag:priority を指定できます。指定ごとに、空白文字で区切ります。

下記のフィルタ式の例の場合、タグ「ActivityManager」が付いたログメッセージのうち優先度が「Info」以上のものと、タグ「MyApp」が付いたログメッセージのうち優先度が「Debug」以上のものだけが表示され、他のログメッセージは非表示になります。

adb logcat ActivityManager:I MyApp:D *:S

上記の式の最後の要素 *:S は、すべてのタグの優先度レベルを「Silent」に設定します。そのため、「ActivityManager」と「MyApp」のタグが付いたログメッセージだけが表示されます。*:S を使用すると、明示的に指定したフィルタによって、ログ出力を効果的に制限できます。つまり、フィルタがログ出力の「許可リスト」として機能します。

次のフィルタ式を使用すると、タグに関係なく、優先度レベルが「Warning」以上のログメッセージがすべて表示されます。

adb logcat *:W

また、リモート adb シェルからではなく、開発用コンピュータから logcat を実行する場合、環境変数 ANDROID_LOG_TAGS の値をエクスポートすることで、デフォルトのフィルタ式を設定できます。

export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"

リモートシェルから logcat を実行している場合や、adb shell logcat を使用している場合、ANDROID_LOG_TAGS フィルタは、エミュレータ / デバイス インスタンスにエクスポートされません。

ログの出力形式を指定する

ログメッセージには、タグと優先度のほかに、さまざまなメタデータ フィールドが含まれています。メッセージの出力形式を変更して、特定のメタデータ フィールドを表示するように設定できます。そのためには、-v オプションを使用して出力形式を指定します。サポートされている出力形式は次のとおりです。

  • brief: 優先度 / タグ、メッセージ発行元プロセスの PID を表示します。
  • long: すべてのメタデータ フィールドを表示し、各メッセージを空行で区切ります。
  • process: PID だけを表示します。
  • raw: 未加工のログメッセージを表示します。他のメタデータ フィールドは表示しません。
  • tag: 優先度 / タグだけを表示します。
  • thread:: 優先度、PID、メッセージ発行元スレッドの TID を表示する従来型の形式。
  • threadtime(デフォルト): 日付、呼び出し時刻、優先度 / タグ、PID、メッセージ発行元スレッドの TID を表示します。
  • time: 日付、呼び出し時刻、優先度 / タグ、メッセージ発行元プロセスの PID を表示します。

logcat を開始するときに、-v オプションを使用することで、必要な出力形式を指定できます。

[adb] logcat [-v <format>]

thread 出力形式でメッセージを生成する例を以下に示します。

adb logcat -v thread

-v オプションで指定できる出力形式は 1 つだけに限られますが、有効な修飾子はいくつでも指定できます。有効でない修飾子は、logcat によって無視されます。

形式修飾子

下記の 1 つ以上の形式修飾子を組み合わせることで、logcat の出力を変更できます。形式修飾子を指定するには、次のように -v オプションを使用します。

adb logcat -b all -v color -d

すべての Android ログメッセージにはタグと優先度が関連付けられています。形式修飾子は任意の形式オプション(brieflongprocessrawtagthreadthreadtimetime)と組み合わせることができます。

コマンドラインで「logcat -v --help」と入力すると、形式修飾子の詳細を表示できます。

  • color: 各優先度を異なる色で表示します。
  • descriptive: ログバッファ イベントの説明を表示します。この修飾子は、イベントログ バッファ メッセージにのみ影響し、他の非バイナリ バッファには影響しません。イベントの説明は、event-log-tags データベースから取得します。
  • epoch: 1970 年 1 月 1 日を起点とする経過時間を秒単位で表示します。
  • monotonic: 前回の起動時を起点とする経過時間を CPU 秒単位で表示します。
  • printable: バイナリ ログコンテンツをエスケープします。
  • uid: アクセス制御によって許可されている場合に、ログに記録されたプロセスの UID または Android ID を表示します。
  • usec: マイクロ秒単位の精度で時刻を表示します。
  • UTC: 時刻を UTC で表示します。
  • year: 表示されている時刻に年を追加します。
  • zone: 表示されている時刻にローカル タイムゾーンを追加します。

代替ログバッファを表示する

Android のログシステムは、複数のサークル バッファを使用してログメッセージを記録しますが、必ずしもすべてのログメッセージがデフォルト サークル バッファに送信されるわけではありません。追加分のログメッセージを表示するには、logcat コマンドに -b オプションを付けて実行し、代替サークル バッファの表示をリクエストします。以下の代替バッファを表示できます。

  • radio: 無線通信や電話に関連するメッセージが格納されるバッファを表示します。
  • events: 解釈されたバイナリ システム イベント バッファ メッセージを表示します。
  • main: デフォルトのメイン ログバッファを表示します。システムログ メッセージとクラッシュログ メッセージはここには格納されません。
  • system: デフォルトのシステムログ バッファを表示します。
  • crash: デフォルトのクラッシュログ バッファを表示します。
  • all: すべてのバッファを表示します。
  • default: mainsystemcrash の各バッファをレポートします。

-b オプションは次のように使用します。

[adb] logcat [-b <buffer>]

無線通信や電話に関連するメッセージを格納しているログバッファを表示する例を以下に示します。

adb logcat -b radio

次のように、出力するバッファごとに -b フラグを指定することもできます。

logcat -b main -b radio -b events

複数のバッファをカンマ区切りで指定する場合は、次のように -b フラグを 1 つだけ指定します。

logcat -b main,radio,events

コードからログを記録する

Log クラスを使用すると、コード内にログエントリを作成して、logcat ツールで表示できます。一般的なログ記録用メソッドは次のとおりです。

たとえば、次の呼び出しを使用します。

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