כלי שורת הפקודה Logcat

Logcat הוא כלי שורת פקודה שיוצר יומן Google של הודעות מערכת, כולל הודעות שכתבת מהאפליקציה באמצעות כיתה אחת (Log).

הדף הזה עוסק בכלי שורת הפקודה logcat, אבל אפשר גם להציג יומן הודעות מהחלון Logcat ב-Android Studio. עבור מידע על הצגה וסינון של יומנים מ-Android Studio, ראה הצגה וכתיבה של יומנים באמצעות Logcat .

סקירה כללית של מערכת הרישום

מערכת הרישום ביומן של Android היא קבוצה של מאגרי נתונים זמניים מובנים, שמופעלת על ידי המערכת תהליך logd. הקבוצה של מאגרי הנתונים הזמניים הזמינים קבועה ומוגדרת על ידי המערכת. מאגר הנתונים הזמני הרלוונטי ביותר הוא:

• main: אחסון של רוב יומני האפליקציות.
• system: שמירת הודעות שמקורן במערכת ההפעלה Android.
• crash: אחסון יומני קריסה. לכל רשומה ביומן יש עדיפות, תג שמזהה מקור היומן והודעת היומן בפועל.

ממשק C/C++ הראשי למערכת הרישום ביומן הוא הספרייה המשותפת liblog והכותרת <android/log.h>. כל מתקני הרישום ביומן הספציפיים לשפה (כולל android.util.Log) לקרוא לפונקציה בסופו של דבר __android_log_write. כברירת מחדל, היא קוראת לפונקציה __android_log_logd_logger, ואז הרשומה ביומן תישלח אל logd באמצעות socket. החל מרמת API 30, אפשר לשנות את פונקציית הרישום ביומן באמצעות קריאה __android_set_log_writer מידע נוסף זמין מסמכי תיעוד של NDK.

היומנים שמוצגים על ידי adb logcat עוברים בארבע רמות סינון:

סינון לפי זמן הידור

בהתאם להגדרות האיסוף, ייתכן שחלק מהיומנים הוסר מהקובץ הבינארי. לדוגמה, ניתן להגדיר את ProGuard למסירת קריאות שנשלחות אל Log.d מקוד Java.

סינון מאפייני המערכת

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. מעבר לקטע על תוכלו לקבל פרטים נוספים על סינון פלט היומן.

התחביר של שורת הפקודה

כדי להריץ את logcat דרך המעטפת adb, השימוש הכללי הוא:

[adb] shell logcat [<option>] ... [<filter-spec>] ...

יש גם קיצור דרך של adb logcat, אבל זה רק מתרחב adb shell logcat.

אפשרויות

ב-logcat יש הרבה אפשרויות. האפשרויות הזמינות תלויות במערכת ההפעלה של המכשיר שבו אתם משתמשים. כדי לראות עזרה לגבי logcat ספציפית אל במכשיר שבו משתמשים, מפעילים:

    adb logcat --help
    

הערה: logcat הוא כלי למפתחים של מערכות הפעלה וגם למפתחי אפליקציות (מפתחים של אפליקציות שאמורים להשתמש ב-Android Studio במקום זאת) רבות מהאפשרויות לשימוש בתור root.

סינון הפלט של היומן

התג של הודעת יומן הוא מחרוזת קצרה שמציינת את רכיב המערכת שבו מקור ההודעה. לדוגמה, 'תצוגה' למערכת התצוגות.

העדיפות היא אחד מערכי התווים הבאים, מסודרים מהנמוך לגבוה עדיפות:

כדי לקבל רשימה של תגים שנמצאים בשימוש במערכת עם סדרי עדיפויות, מפעילים את הפקודה logcat ובוחנים את שתי העמודות הראשונות של כל הודעה, שמופיעות בתור <priority>/<tag>.

הדוגמה הבאה היא של פלט קצר של logcat שהתקבל באמצעות הפונקציה הפקודה logcat -v brief output. הפלט מראה שההודעה קשורה רמת עדיפות I ואת התג 'ActivityManager':

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

כדי לצמצם את פלט היומן לרמה שאפשר לנהל, צריך להגביל את פלט היומן באמצעות סינון . ביטויי סינון מאפשרים לציין למערכת את עדיפות התג של הנכסים שמעניינים אותך. המערכת משביתה הודעות אחרות עבור התגים שצוינו.

ביטוי סינון תואם לפורמט הבא: tag:priority ..., שבו tag מציין את התג הרצוי ו-priority מציין את הרמה המינימלית של עדיפות לדיווח על אותו תג. הודעות לתג הזה שנמצאות בעדיפות שצוינה או גבוהות ממנה שכתוב ביומן. לספק כל מספר של מפרטים של tag:priority ביטוי סינון יחיד. סדרת המפרטים מופרדת ברווחים לבנים.

הדוגמה הבאה היא של ביטוי סינון ש מסתיר את כל הודעות היומן, מלבד עסקים עם התג 'ActivityManager' בעדיפות גבוהה, "מידע" או מילות מפתח עם התג "MyApp" עם עדיפות ל'ניפוי באגים' או יותר:

adb logcat ActivityManager:I MyApp:D *:S

הרכיב האחרון בביטוי הקודם, *:S, מגדיר את רמת העדיפות של את כל התגים ל-'silent', וכך מובטחת ביומן הודעות רק עםActivityManager. ו-MyApp הן מוצגת. השימוש ב-*:S מבטיח שפלט היומן יוגבל ל- המסננים שציינת במפורש. *:S מאפשר למסננים לשמש רשימת היתרים לפלט היומן.

הערה: בחלק מהמעטפות, השדה "*" נשמר על ידי המעטפת. אם משתמשים במעטפת כזו, צריך לתחום את ביטוי הסינון במירכאות: adb logcat "ActivityManager:I MyApp:D *:S"

ביטוי הסינון הבא מציג את כל הודעות היומן עם 'אזהרה' ברמת העדיפות וגם גבוה יותר בכל התגים:

adb logcat *:W

אם מפעילים את logcat ממחשב הפיתוח במקום להריץ אותו על המעטפת המרוחקת adb, אפשר גם להגדיר ביטוי סינון כברירת מחדל על ידי ייצוא ערך משתנה הסביבה ANDROID_LOG_TAGS:

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

המסנן ANDROID_LOG_TAGS לא מיוצא לאמולטור או למכשיר למשל אם מריצים את הפקודה logcat ממעטפת מרוחקת או משתמשים ב-adb shell logcat.

בקרה על פורמט הפלט של היומן

הודעות היומן מכילות כמה שדות של מטא-נתונים, נוסף על התג והעדיפות. אפשר לשנות את פורמט הפלט של הודעות כך שיציגו שדה מטא-נתונים ספציפי. כדי לעשות את זה, להשתמש באפשרות -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. אבל, שאפשר לציין כמה משתנים שצריך, כל עוד הם הגיוניים. 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: הצגת הזמן בשניות החל מ-1 בינואר 1970.
• monotonic: הצגת הזמן בשניות במעבד (CPU) החל מההפעלה האחרונה.
• printable: מבטיח שכל תוכן בינארי ברישום ביומן סומן בתו בריחה (escape).
• uid: אם ניתן להשתמש בבקרת גישה, יוצג מזהה ה-UID או Android של שתועד.
• usec: הצגת השעה, בדיוק במיליוניות השנייה.
• UTC: הצגת השעה כ-UTC.
• year: הוספת השנה לזמן המוצג.
• zone: הוספת אזור הזמן המקומי לשעה שמוצגת.

הצגת מאגרי יומנים חלופיים

מערכת הרישום של Android שומרת מאגר נתונים עגול רבים בהודעות ביומן, ולא את כולם הודעות היומן נשלחות למאגר הנתונים העגול שמוגדר כברירת מחדל. כדי לראות הודעות נוספות ביומן: מריצים את הפקודה logcat עם האפשרות -b כדי לבקש הצגה של מאגר נתונים זמני ומעגלי. אפשר להציג כל אחד ממאגרי הנתונים החלופיים הבאים:

• 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