為配合主幹穩定開發模型，並確保生態系統的平台穩定性，我們將自 2026 年起，在第 2 季和第 4 季將原始碼發布至 AOSP。如要建構及貢獻 AOSP，請使用 android-latest-release。android-latest-release 資訊清單分支版本一律會參照推送至 Android 開放原始碼計畫的最新版本。詳情請參閱「Android 開放原始碼計畫變更」。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

IMetricCollector

public interface IMetricCollector
implements IDisableable, ILogSaverListener

com.android.tradefed.device.metric.IMetricCollector

已知間接子類別

AtraceCollector、AtraceRunMetricCollector、BaseDeviceMetricCollector、BluetoothConnectionLatencyCollector、BluetoothConnectionStateCollector、BluetoothHciSnoopLogCollector、BugreportzOnFailureCollector、BugreportzOnTestCaseFailureCollector、ClangCodeCoverageCollector、CodeCoverageCollector、CountTestCasesCollector、DebugHostLogOnFailureCollector、DeviceTraceCollector、FilePullerDeviceMetricCollector、FilePullerLogCollector 等 16 個收集器。

AtraceCollector	`IMetricCollector`：在測試期間執行追蹤，並收集結果和記錄到呼叫中。
AtraceRunMetricCollector	從測試裝置收集指定目錄下所有測試目錄的追蹤記錄、記錄測試目錄，並後續處理測試目錄下的追蹤記錄檔案，以及匯總指標。
BaseDeviceMetricCollector	`IMetricCollector` 的基本實作，可讓您在 `onTestRunStart(DeviceMetricData)` 和 `onTestRunEnd(DeviceMetricData,Map)` 上開始及停止收集資料。
BluetoothConnectionLatencyCollector	收集器會將預先定義的 statsd 持續時間指標設定推送至裝置，並收集每個設定檔的藍牙連線持續時間。
BluetoothConnectionStateCollector	這個收集器會收集 BluetoothConnectionStateChanged 指標，並記錄每個設定檔的連線狀態編號。
BluetoothHciSnoopLogCollector	收集器，用於在 DUT 上啟用藍牙 HCI 窺探記錄，並收集各項測試的記錄。
BugreportzOnFailureCollector	測試案例失敗時，收集 bugreportz。
BugreportzOnTestCaseFailureCollector	在執行測試案例時，如果發生失敗情形，請收集錯誤報告。
ClangCodeCoverageCollector	`BaseDeviceMetricCollector`，可從裝置中提取 Clang 涵蓋範圍測量結果，並將其記錄為測試構件。
CodeCoverageCollector	`BaseDeviceMetricCollector`，可從裝置中提取 Java 和原生涵蓋範圍測量結果，並將其記錄為測試構件。
CountTestCasesCollector	計算並回報指定 `IRemoteTest` 的測試案例數量。
DebugHostLogOnFailureCollector	收集器會在測試案例失敗時收集並記錄主機端記錄。
DeviceTraceCollector	這個收集器會在測試執行開始時啟動 Perfetto 追蹤記錄，並在結束時記錄追蹤記錄檔。
FilePullerDeviceMetricCollector	`BaseDeviceMetricCollector`，可監聽裝置傳來的指標金鑰，並從裝置中擷取這些金鑰做為檔案。
FilePullerLogCollector	記錄裝置端回報的檔案。
GcovCodeCoverageCollector	`BaseDeviceMetricCollector`，可從裝置中提取 gcov 涵蓋範圍測量結果，並將其記錄為測試構件。
GcovKernelCodeCoverageCollector	這項工具會從 debugfs 和裝置中提取 gcov 核心涵蓋範圍測量結果，然後將這些結果記錄為測試構件。`BaseDeviceMetricCollector`
HostStatsdMetricCollector	`IMetricCollector`：使用 statsd 公用程式指令從主機端收集 statsd 指標。
JavaCodeCoverageCollector	`BaseDeviceMetricCollector`，可從裝置中提取 Java 涵蓋範圍測量結果，並將其記錄為測試構件。
LogcatOnFailureCollector	收集器：在測試案例或測試執行失敗時擷取並記錄 logcat。
LogcatTimingMetricCollector	指標收集器，可使用指定的 regex 模式剖析 logcat 行中的事件開始和結束信號，在一次或多次重複測試期間，從 logcat 收集時間資訊 (例如使用者切換時間)。
ModuleLogcatCollector	Logcat 收集器版本，但適用於模組。
ModulePerfettoCollector	這個收集器會在測試模組啟動/結束時和裝置重新啟動時，啟動 perfetto 追蹤。
PerfettoFilePullerCollector	收集器會從裝置提取 Perfetto 追蹤記錄檔案，並視需要壓縮檔案，然後將檔案新增至測試記錄。
PerfettoPullerMetricCollector	這個類別已淘汰。請改用 `PerfettoFilePullerCollector` 和 `ERROR(/PerfettoTracePostProcessor)`。
RebootReasonCollector	收集測試執行期間裝置重新啟動的次數，並依據原因和次數回報。
RuntimeRestartCollector	收集器，用於收集測試執行期間的執行階段重新啟動時間戳記 (系統伺服器當機)，如有。
ScreenRecordOnFailureCollector	收集器會在測試案例失敗時擷取並記錄螢幕錄影。
ScreenshotOnFailureCollector	收集器，會在測試案例失敗時擷取並記錄螢幕截圖。
ShowmapPullerMetricCollector	`FilePullerDeviceMetricCollector` 的基本實作，可從裝置中提取 showmap 檔案，並從中收集指標。
TraceCmdCollector	`IMetricCollector`：使用 trace-cmd 在測試期間收集追蹤記錄，並將記錄寫入呼叫。

回報測試結果時，這個介面會以裝飾器形式新增，以便收集相符的指標。

即使這個介面會擴充 ITestInvocationListener，也無法做為使用。設定檢查會拒絕這項要求。必須做為「metrics_collector」使用。

收集器不應保留內部狀態，因為收集器可能會在多個位置重複使用。如果真的必須使用內部狀態，則應在 init(IInvocationContext,ITestInvocationListener) 上清除。

摘要

公用方法
`default boolean`	`captureModuleLevel()` 收集器是否適用於模組層級擷取，且應初始化。
`default boolean`	`doesModuleContainFailure()` 如果目前模組包含任何測試案例或測試執行失敗，則傳回 true。
`default void`	`enableDefaultMetricCollection()` 允許收集器啟用預設指標收集功能。
`default IMetricCollector.MetricCollectionLevel`	`getAlwaysOnCollectionLevel()`
`abstract List<IBuildInfo>`	`getBuildInfos()` 傳回可供呼叫使用的建構資訊清單。
`abstract List<ITestDevice>`	`getDevices()` 傳回呼叫中可用的裝置清單。
`abstract ITestInvocationListener`	`getInvocationListener()` 傳回轉送結果的原始 `ITestInvocationListener`。
`default IMetricCollector.MetricCollectionLevel`	`getOnFailureCollectionLevel()`
`abstract ITestInvocationListener`	`init(IInvocationContext context, ITestInvocationListener listener)` 使用目前環境初始化收集器，並指定轉送結果的位置。
`default boolean`	`isDefaultMetricCollectionEnabled()` 收集器是否正在收集指標，做為預設指標收集作業的一部分。
`abstract void`	`onTestAssumptionFailure(DeviceMetricData testData, TestDescription test)` 測試案例因假設失敗而失敗時的回呼。
`abstract void`	`onTestEnd(DeviceMetricData testData, Map<String, MetricMeasurement.Metric> currentTestCaseMetrics, TestDescription test)` 測試案例結束時的回呼。
`abstract void`	`onTestEnd(DeviceMetricData testData, Map<String, MetricMeasurement.Metric> currentTestCaseMetrics)` 測試案例結束時的回呼。
`abstract void`	`onTestFail(DeviceMetricData testData, TestDescription test)` 測試案例失敗時的回呼。
`default void`	`onTestModuleEnded()` 允許擷取模組結束事件。
`default void`	`onTestModuleStarted()` 允許擷取模組啟動事件。
`abstract void`	`onTestRunEnd(DeviceMetricData runData, Map<String, MetricMeasurement.Metric> currentRunMetrics)` 測試作業結束時的回呼。
`abstract void`	`onTestRunStart(DeviceMetricData runData)` 測試執行開始時的回呼。
`default void`	`onTestRunStart(DeviceMetricData runData, int testCount)` 測試執行開始時的回呼。
`default void`	`onTestRunStartBlocking()` Explicit callback to start a collector manually if it supports it.
`abstract void`	`onTestStart(DeviceMetricData testData)` 測試案例啟動時的回呼。
`default void`	`setAlwaysOnCollectionLevel(IMetricCollector.MetricCollectionLevel level)` 設定收集器應收集記錄的層級，無論是否發生失敗。
`default void`	`setModuleContainsFailure()` 設定模組是否有任何失敗 (測試案例、測試執行)。
`default void`	`setOnFailureCollectionLevel(IMetricCollector.MetricCollectionLevel level)` Sets the level at which the collector should collect logs during failures.

公用方法

captureModuleLevel

public boolean captureModuleLevel ()

收集器是否適用於模組層級擷取，且應進行初始化。

傳回
`boolean`

doesModuleContainFailure

public boolean doesModuleContainFailure ()

如果目前模組包含任何測試案例或測試執行失敗，則傳回 true。

傳回
`boolean`

enableDefaultMetricCollection

public void enableDefaultMetricCollection ()

允許收集器啟用預設指標收集功能。啟用預設指標收集功能後，收集器應只在指定的收集層級收集資料。

getAlwaysOnCollectionLevel

public IMetricCollector.MetricCollectionLevel getAlwaysOnCollectionLevel ()

傳回
`IMetricCollector.MetricCollectionLevel`

getBuildInfos

public abstract List<IBuildInfo> getBuildInfos ()

傳回可供呼叫使用的建構資訊清單。

傳回
`List<IBuildInfo>`

getDevices

public abstract List<ITestDevice> getDevices ()

傳回呼叫中可用的裝置清單。

傳回
`List<ITestDevice>`

getInvocationListener

public abstract ITestInvocationListener getInvocationListener ()

傳回要轉送結果的原始 ITestInvocationListener。

傳回
`ITestInvocationListener`

getOnFailureCollectionLevel

public IMetricCollector.MetricCollectionLevel getOnFailureCollectionLevel ()

傳回
`IMetricCollector.MetricCollectionLevel`

init

public abstract ITestInvocationListener init (IInvocationContext context, 
                ITestInvocationListener listener)

使用目前環境初始化收集器，並指定轉送結果的位置。每個執行個體只會呼叫一次，收集器應更新其內部環境和接聽程式。在測試執行期間，系統一律不會呼叫 Init，而是會先呼叫。

除非您知道自己在做什麼，否則請勿覆寫。

參數
`context`	`IInvocationContext`：正在進行的呼叫的 `IInvocationContext`。
`listener`	`ITestInvocationListener`：要放置結果的 `ITestInvocationListener`。

傳回
`ITestInvocationListener`	新監聽器包裝原始監聽器。

擲回
`DeviceNotAvailableException`

isDefaultMetricCollectionEnabled

public boolean isDefaultMetricCollectionEnabled ()

收集器是否正在收集指標，做為預設指標收集作業的一部分。

傳回
`boolean`

onTestAssumptionFailure

public abstract void onTestAssumptionFailure (DeviceMetricData testData, 
                TestDescription test)

測試案例因假設失敗而失敗時的回呼。

參數
`testData`	`DeviceMetricData`：保存測試案例資料的 `DeviceMetricData`。
`test`	`TestDescription`：進行中測試案例的 `TestDescription`。

擲回
`DeviceNotAvailableException`

onTestEnd

public abstract void onTestEnd (DeviceMetricData testData, 
                Map<String, MetricMeasurement.Metric> currentTestCaseMetrics, 
                TestDescription test)

測試案例結束時的回呼。這時應進行清理。

參數
`testData`	`DeviceMetricData`：保存測試案例資料的 `DeviceMetricData`。與 `onTestStart(DeviceMetricData)` 期間的物件相同。
`currentTestCaseMetrics`	`Map`：傳遞至 `testEnded(TestDescription,Map)` 的指標目前對應。
`test`	`TestDescription`：進行中測試案例的 `TestDescription`。

擲回
`DeviceNotAvailableException`

onTestEnd

public abstract void onTestEnd (DeviceMetricData testData, 
                Map<String, MetricMeasurement.Metric> currentTestCaseMetrics)

測試案例結束時的回呼。這時應進行清理。

參數
`testData`	`DeviceMetricData`：保存測試案例資料的 `DeviceMetricData`。與 `onTestStart(DeviceMetricData)` 期間的物件相同。
`currentTestCaseMetrics`	`Map`：傳遞至 `testEnded(TestDescription,Map)` 的指標目前對應。

擲回
`DeviceNotAvailableException`

onTestFail

public abstract void onTestFail (DeviceMetricData testData, 
                TestDescription test)

測試案例失敗時的回呼。

參數
`testData`	`DeviceMetricData`：保存測試案例資料的 `DeviceMetricData`。
`test`	`TestDescription`：進行中測試案例的 `TestDescription`。

擲回
`DeviceNotAvailableException`

onTestModuleEnded

public void onTestModuleEnded ()

允許擷取模組結束事件。

擲回
	com.android.tradefed.device.DeviceNotAvailableException
`DeviceNotAvailableException`

onTestModuleStarted

public void onTestModuleStarted ()

允許擷取模組啟動事件。

擲回
	com.android.tradefed.device.DeviceNotAvailableException
`DeviceNotAvailableException`

onTestRunEnd

public abstract void onTestRunEnd (DeviceMetricData runData, 
                Map<String, MetricMeasurement.Metric> currentRunMetrics)

測試作業結束時的回呼。這時應進行清理。

參數
`runData`	`DeviceMetricData`：`DeviceMetricData`，其中包含執行作業的資料。與 `onTestRunStart(DeviceMetricData)` 期間的物件相同。
`currentRunMetrics`	`Map`：傳遞至 `testRunEnded(long,Map)` 的指標目前對應。

擲回
`DeviceNotAvailableException`

onTestRunStart

public abstract void onTestRunStart (DeviceMetricData runData)

測試執行開始時的回呼。

參數
`runData`	`DeviceMetricData`：`DeviceMetricData`，其中包含執行作業的資料。

擲回
`DeviceNotAvailableException`

onTestRunStart

public void onTestRunStart (DeviceMetricData runData, 
                int testCount)

測試執行開始時的回呼。

參數
`runData`	`DeviceMetricData`：`DeviceMetricData`，其中包含執行作業的資料。
`testCount`	`int`：這項測試執行作業中的測試案例數量。

擲回
`DeviceNotAvailableException`

onTestRunStartBlocking

public void onTestRunStartBlocking ()

如果收集器支援，可明確回呼以手動啟動收集器。這可確保我們已脫離某些非同步測試生命週期。

擲回
	com.android.tradefed.device.DeviceNotAvailableException
`DeviceNotAvailableException`

onTestStart

public abstract void onTestStart (DeviceMetricData testData)

測試案例啟動時的回呼。

參數
`testData`	`DeviceMetricData`：保存測試案例資料的 `DeviceMetricData`。

擲回
`DeviceNotAvailableException`

setAlwaysOnCollectionLevel

public void setAlwaysOnCollectionLevel (IMetricCollector.MetricCollectionLevel level)

設定收集器應收集記錄的層級，無論是否發生故障。

如果層級為 NULL，系統就不會收集資料。

參數
`level`	`IMetricCollector.MetricCollectionLevel`：收集記錄的 `MetricCollectionLevel`。

setModuleContainsFailure

public void setModuleContainsFailure ()

設定模組是否有任何失敗 (測試案例、測試執行)。

setOnFailureCollectionLevel

public void setOnFailureCollectionLevel (IMetricCollector.MetricCollectionLevel level)

設定收集器在發生失敗時應收集記錄的層級。

如果層級為 NULL，系統就不會收集資料。

參數
`level`	`IMetricCollector.MetricCollectionLevel`：收集記錄的 `MetricCollectionLevel`。