اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.
يمكنك تسجيل عمليات التتبُّع باستخدام Winscope لتطوير التطبيقات وتصحيح الأخطاء على الجهاز.
يستخدم Winscope أداة adb التي تتيح
الاتصال بالجهاز عبر USB أو Wi-Fi.
تظهر شاشة Collect Traces (جمع عمليات التتبّع) عند تشغيل Winscope.
يُرجى ملاحظة رمز موفِّر خادم الوكيل Winscope المعروض على المحطة الطرفية بعد التنفيذ.
بعد تشغيل وكيل Winscope ADB Connect، تتغيّر الشاشة على النحو التالي:
لإنشاء الاتصال الأوّلي بالخادم الوكيل، أدخِل
الرمز المميّز لخادم الوكيل Winscope من الخطوة 3 وانقر على ربط.
الشكل 2: اتّصل بخادم Winscope الوكيل.
إعداد وكيل الجهاز على الويب
اتّبِع الخطوات التالية لإعداد Web Device Proxy:
ضمن جمع عمليات التتبّع في الصفحة الرئيسية، اختَر وكيل أجهزة الويب في القائمة المنسدلة
اختيار نوع الاتصال:
الشكل 3: تسجيل عمليات التتبّع باستخدام Web Device Proxy
إذا لم يكن برنامج Web Device Proxy daemon مثبّتًا على جهازك، انقر على تثبيت أو شغِّل مُثبِّت.
عليك الموافقة على وصول المصدر إلى "خادم الوكيل لأجهزة الويب" من خلال مربّع الحوار.
الشكل 4: عليك تفويض المصدر.
عليك الموافقة على الوصول إلى كل جهاز جديد في المرة الأولى التي تتصل فيها بالجهاز.
إذا لم يظهر مربّع الحوار تلقائيًا، انقر على رمز lock_open بجانب
الجهاز:
الشكل 5: عليك تفويض الجهاز.
عمليات التتبّع
اتّبِع الخطوات التالية لجمع عمليات التتبّع:
عند الاتصال، لبدء عملية الالتقاط، اختَر الاستهدافات و
ضبط الإعدادات. بعد ذلك، انقر على بدء التتبُّع لبدء التسجيل:
الشكل 6: جمع عمليات التتبُّع في Winscope
لإيقاف عملية التقاط البيانات، انقر على إنهاء التتبُّع:
الشكل 7: إنهاء التتبّع في Winscope
خيارات التتبّع
يصف هذا القسم خيارات كل نوع من أنواع التتبّع.
تسجيل الشاشة
باستخدام Winscope، يمكنك تسجيل شاشة شاشات متعددة. اختَر شاشة
من القائمة لتسجيل الشاشة. في حال عدم تحديد أي شاشة، يسجِّل Winscope
الشاشة النشطة تلقائيًا.
SurfaceFlinger
حجم ذاكرة التخزين المؤقت: لضبط حجم ذاكرة التخزين المؤقت الدائرية في الذاكرة لمسار traced.
SurfaceFlinger يتيح المخزن المؤقت الأكبر حجمًا جمع المزيد من البيانات، ولكنه يزيد من استخدام الذاكرة.
الإدخال: إذا كانت المساحة تحتوي على بيانات إدخال، يتم تتبُّع تفاصيل
نافذة الإدخال.
التركيب: يتتبّع نوع التركيبة والمنطقة المرئية.
البيانات الوصفية: تتتبّع البيانات الوصفية الإضافية للسطح، بما في ذلك المستويات
غير المعروضة على الشاشة.
HWC: تتتبّع البيانات الوصفية الإضافية غير المنظَّمة لمُنشئ الأجهزة.
تتبُّع المخزن المؤقت: لضبط SurfaceFlinger لتتبُّع جميع تغييرات المخزن المؤقت على سطح الشاشة
لا يتتبّع SurfaceFlinger حالة جديدة تلقائيًا إلا عند
تغيير الشكل الهندسي.
الشاشات الافتراضية: تتضمّن طبقات الشاشات الافتراضية في التتبُّع.
WindowManager
حجم ذاكرة التخزين المؤقت: لضبط حجم ذاكرة التخزين المؤقت الدائرية في الذاكرة لمسار traced.
WindowManager يتيح المخزن المؤقت الأكبر حجمًا جمع المزيد من البيانات، ولكنه
يزيد من استخدام الذاكرة.
نوع التتبُّع: يحدِّد خيارات تكرار جمع الحالات:
frame: في هذا الوضع، يُفرِغ WindowManager حالة واحدة لكل
إطار، ما يضمن تسجيل حالات WindowManager الصالحة فقط. يتميز هذا
الوضع بأقلّ أعباء الأداء.
transaction: يسجِّل هذا الوضع حالة WindowManager عند إتمام
معاملة. يمكنك إرسال معاملات متعددة ضمن
إطار، ما يسمح بتصحيح أخطاء حالات
WindowManager الوسيطة أثناء عرض إطار. ومع ذلك، يستهلك هذا الوضع موارد أعلى مقارنةً بوضع اللقطات.
مستوى التتبُّع: يحدِّد مستوى تفصيل عمليات تتبُّع WindowManager:
verbose: يتضمّن جميع النوافذ ومعلومات الضبط لكل
نافذة. يستهلك هذا الوضع أكبر قدر من الذاكرة ويؤدي إلى انخفاض الأداء.
debug: يتضمّن معلومات عن جميع النوافذ، ولكنّه لا يسجّل سوى
إعدادات النافذة إذا كانت تحتوي على إعدادات إلغاء مطلوبة.
المستوى الحرج: يتضمّن المعلومات نفسها المتوفّرة في "وضع تصحيح الأخطاء"، ولكنّه يتضمّن
النوافذ المرئية فقط. يتميز هذا الوضع بأقل قدر من استهلاك الذاكرة والأداء.
عمليات تفريغ
لإنشاء ملف تخزين مؤقت للحالة باستخدام Winscope، ضمن جمع عمليات التتبّع على الصفحة الرئيسية،
اختَر علامة التبويب تخزين مؤقت، ثم انقر على تخزين حالة:
الشكل 8: نسخ الحالة في Winscope
ضبط لقطة الشاشة
يتيح تطبيق Winscope أخذ لقطة شاشة لشاشات متعددة. اختَر شاشة من
القائمة لأخذ لقطة شاشة لها. في حال عدم إجراء أي اختيار، يتم جمع لقطة شاشة
للشاشة النشطة.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Capture traces with Winscope\n\n[Run Winscope](/docs/core/graphics/winscope/run) locally or access it\nfrom a web server.\n\nYou can capture traces using Winscope for local development and debugging.\nWinscope uses [adb](https://developer.android.com/tools/adb), which supports\ndevice connection over USB or Wi-Fi.\n\nThe **Collect Traces** screen is displayed on launching Winscope.\n\nDevice connection\n-----------------\n\nYou can connect devices in Winscope using\n[Winscope Proxy](#winscope-proxy-setup)\nor\n[Web Device Proxy](#web-device-proxy-setup).\nBy default, the Winscope homepage shows the **Winscope Proxy** connection setup\nUI.\n\nTo start capturing traces, choose one of the following device connection\nmechanisms.\n\n### Winscope Proxy setup\n\nFollow these steps to set up Winscope Proxy:\n\n1. Under **Collect Traces** on the homepage, choose **Winscope Proxy** in the\n **Select connection type** drop-down:\n\n **Figure 1.** Capture traces using Winscope Proxy.\n2. Launch the Winscope ADB Connect proxy to capture traces directly from your\n browser, by running the following command:\n\n python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py\n\n | **Note:** Python 3.10+ and adb are required.\n3. Note the Winscope proxy token displayed on the terminal after execution.\n\n4. After you launch the Winscope ADB Connect proxy, the screen changes as\n follows. To establish the initial connection to the proxy, input the\n Winscope proxy token from step 3 and click **Connect**.\n\n **Figure 2.** Connect to Winscope Proxy.\n\n### Web Device Proxy setup\n\nFollow these steps to set up Web Device Proxy:\n\n1. Under **Collect Traces** on the homepage, choose **Web Device Proxy** in the\n **Select connection type** drop-down:\n\n **Figure 3.** Capture traces using Web Device Proxy.\n2. If you don't have the Web Device Proxy daemon on your machine, click\n **Install** or run the\n [installer](https://tools.google.com/dlpage/android_web_device_proxy).\n\n | **Note:** Web Device Proxy is not yet supported on Mac.\n3. Approve origin access to Web Device Proxy through the dialog.\n\n **Figure 4.** Authorize origin.\n4. Approve access for each new device the first time you connect to the device.\n If the dialog does not automatically appear, click the `lock_open` icon next\n to the device:\n\n **Figure 5.** Authorize device.\n\nTraces\n------\n\nFollow these steps to collect traces:\n\n1. When connected, to initiate the capture process, select the targets and\n configure the settings. Then click **Start trace** to begin the capture:\n\n **Figure 6.** Collect traces in Winscope.\n2. To stop the capture, click **End trace**:\n\n **Figure 7.** End trace in Winscope.\n\nTrace options\n-------------\n\nThis section describes the options for each trace type.\n\n### Screen recording\n\nWith Winscope, you can record the screen of multiple displays. Choose a display\nfrom the menu to screen record. If you don't make a selection, Winscope records\nthe active display by default.\n| **Note:** Multi-display selection is available only with adb `screenrecord` v1.4 and higher, that is builds from September 2024 on. Single display selection is available for any version earlier than that.\n\n### SurfaceFlinger\n\n- **Buffer size:** Adjusts the size of the in-memory ring buffer for the\n SurfaceFlinger trace. A larger buffer enables the collection of more data\n but increases memory usage.\n\n | **Note:** Buffer size is deprecated starting in Android 15.\n- **Input:** If the surface contains input data, tracks the specifics of\n the input window.\n\n- **Composition:** Traces the composition type and visible region.\n\n- **Metadata:** Traces additional surface metadata, including offscreen\n layers.\n\n | **Warning:** Metadata is highly verbose and requires a large amount of memory.\n- **HWC:** Traces additional unstructured hardware composer metadata.\n\n | **Warning:** HWC is highly verbose and requires a large amount of memory.\n- **Trace buffers:** Configures SurfaceFlinger to trace all buffer changes on\n the surface. By default, SurfaceFlinger traces a new state only when the\n geometry is altered.\n\n- **Virtual displays:** Includes virtual display layers in the trace.\n\n### WindowManager\n\n- **Buffer size:** Adjusts the size of the in-memory ring buffer for the WindowManager trace. A larger buffer enables the collection of more data but increases memory usage.\n- **Tracing type:** Defines the frequency options for collecting states:\n\n - *frame:* In this mode, the WindowManager dumps a single state per frame, ensuring that only valid WindowManager states are captured. This mode has the lowest performance overhead.\n - *transaction:* This mode records a WindowManager state whenever a transaction is committed. You can commit multiple transactions within a frame, so this allows for debugging intermediate WindowManager states during a frame. However, this mode has a higher performance overhead compared to the frame mode.\n- **Tracing level:** Determines the verbosity of the WindowManager traces:\n\n - *verbose:* Includes all windows and configuration information for each window. This mode has the highest memory and performance overhead.\n - *debug:* Includes information about all windows, but logs only the window configuration if it contains a requested override configuration.\n - *critical:* Includes the same information as Debug mode, but includes only visible windows. This mode has the smallest memory and performance overhead.\n\nDumps\n-----\n\nTo take a state dump using Winscope, under **Collect Traces** on the homepage\nselect the **Dump** tab and then click **Dump state**:\n\n**Figure 8.** Dump state in Winscope.\n\n### Screenshot configuration\n\nWinscope allows taking a screenshot for multiple displays. Choose a display from\nthe menu to screenshot. If no selection is made, a screenshot is collected for\nthe active display."]]
