基準

宣告依附元件

如要新增基準的依附元件，必須將 Google Maven 存放區新增至專案。詳情請參閱「Google 的 Maven 存放區」一節。

Macrobenchmark

如要在專案中使用 Macrobenchmark，請將以下依附元件加入macrobenchmark 模組的 build.gradle 檔案中：

dependencies {
  androidTestImplementation "androidx.benchmark:benchmark-macro-junit4:1.3.4"
}

dependencies {
  androidTestImplementation("androidx.benchmark:benchmark-macro-junit4:1.3.4")
}

Microbenchmark

如要在專案中使用 Microbenchmark，請將以下依附元件加入microbenchmark 模組的 build.gradle 檔案中：

dependencies {
    androidTestImplementation "androidx.benchmark:benchmark-junit4:1.3.4"
}

android {
    ...
    defaultConfig {
        ...
        testInstrumentationRunner "androidx.benchmark.junit4.AndroidBenchmarkRunner"
    }
}

dependencies {
    androidTestImplementation("androidx.benchmark:benchmark-junit4:1.3.4")
}

android {
    ...
    defaultConfig {
        ...
        testInstrumentationRunner = "androidx.benchmark.junit4.AndroidBenchmarkRunner"
    }
}

Microbenchmark 程式庫也提供 Gradle 外掛程式，可與 microbenchmark 模組搭配使用。這個外掛程式會訂出模組建構設定的預設值，建立傳到主機的基準輸出內容副本，並提供 ./gradlew lockClocks 工作。

如要使用外掛程式，請在頂層 build.gradle 檔案的「plugins」區塊中加入以下這行程式碼：

plugins {
  id 'androidx.benchmark' version '1.3.4' apply false
}

plugins {
  id("androidx.benchmark") version "1.3.4" apply false
}

接著，將外掛程式套用到基準模組的 build.gradle 檔案

plugins {
  id 'androidx.benchmark'
}

plugins {
    id("androidx.benchmark")
}

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件。

1.4 版

1.4.0-beta01 版本

2025 年 5 月 7 日

發布 androidx.benchmark:benchmark-*:1.4.0-beta01。1.4.0-beta01 版包含這些修訂項目。

API 變更

• 新增可接受 PerfettoConfig 的 PerfettoTraceRule 建構函式變體 (Ie53ba)

修正錯誤

• 更新 TraceProcessor 啟動洞察連結格式，以便使用正確的外掛程式，並提供更清楚的分隔符號 (: 比 %3A 短，且兩者皆受支援) (Ie18ef)
• 請一律使用強制停止功能終止程序，即使是已取得 root 權限並終止系統應用程式也一樣。修正表單 Expected no stdout/stderr from killall ... No such process 的例外狀況。(Idca2c)

外部貢獻

• 新增 TraceProcessorHttpServer 的 Proxy 例外狀況處理常式 (I480f5)

1.4.0-alpha11 版本

2025 年 4 月 9 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha11。1.4.0-alpha11 版包含這些修訂項目。

API 變更

• 變更 TraceProcessor 的引數逾時：將時間長度變更為 timeoutMs，以便 Java 呼叫端使用。(I9fbb5)。
• 將 TraceProcessor 建構函式標示為內部函式。呼叫端應使用 TraceProcessor.startServer 或 TraceProcessor.runServer。(Ia8c5b)。

修正錯誤

• 使用 MacrobenchmarkScope.killProcess 終止應用程式時，請驗證終止指令結果，以免發生無聲失敗和逾時錯誤。(I84555)。

依附元件更新

• 此程式庫現在指定 Kotlin 2.0 語言層級，且需要 KGP 2.0.0 以上版本。(Idb6b5)。

1.4.0-alpha10 版本

2025 年 3 月 26 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha10。1.4.0-alpha10 版包含這些修訂項目。

API 變更

• 將 TraceProcessor 伺服器負載和查詢的預設逾時時間提高至 120 秒 (先前為 60/30 秒)，並讓這兩項功能都能透過單一逾時參數進行設定。(Ifec87)。

修正錯誤

• 修正了在沒有 profileinstaller 的情況下，對應用程式進行基準測試或擷取設定檔時，可能發生的幾個問題，並包含 BroadcastReciever。這項問題只會影響在已解鎖裝置上執行的應用程式。(Ied308)。

1.4.0-alpha09 版本

2025 年 3 月 12 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha09。1.4.0-alpha09 版包含這些修訂項目。

API 變更

• 新增 TraceProcessor 和 Session API，並提供可關閉的句柄，方便搭配自訂生命週期使用。這也是讓您更輕鬆地使用協同程式和 Java API 的一步。TraceProcessor.runServer {} 的擴充功能現在已標示為實驗功能，因為這些功能可能會移至未來的非實驗版本。(I358b4)。

修正錯誤

• 修正基準和基準設定檔擷取功能無法與 API 36 搭配運作的問題，因為 pgrep 玩具盒發生變更，現在需要 -a 才能列印完整的指令列。(Idc991)
• 篩選預設追蹤設定，降低新版 API 級別追蹤資料遺失的風險。(I54e8a)
• 新增實驗性 androidx.benchmark.killExistingPerfettoRecordings 檢測引數，可設為 false，以便繼續執行先前的 Perfeto 追蹤記錄擷取作業。根據預設，裝置上先前存在的 Perfeto 追蹤記錄會遭到終止，以免發生干擾。(I02a3c)。
• 對於 API 35 以上版本的已發布 OS 版本，JSON 欄位 context.osCodenameAbbreviated 現為 REL，因為基礎平台不再支援非數字的代碼名稱。(Ib17fd)。
• 修正在重新同步影格時，FrameTimingMetric 發生異常終止的問題。(I7c6f4、b/394610806)。
• 不再假設 Choreographer#doFrame 是 FrameTimingQuery 主執行緒上堆疊框架的頂端。(Iee0e0、b/340206285)。

1.4.0-alpha08 版本

2025 年 2 月 12 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha08。1.4.0-alpha08 版包含這些修訂項目。

API 變更

• 將 TraceProcessor.runSession() 擴充功能 API 移至實驗階段，因為這些 API 可能會在 Android 上最終轉換為具體建構函式。(Ib0528、b/393640753)
• 啟動時分析的大部分實作項目現已公開/實驗，並移至 TraceProcessor 構件。請參閱 StartupInsights。(I0aa00)
• 棄用 BenchmarkRule.runWithTimingDisabled {}，改用 BenchmarkRule.runWithMeasurementDisabled {}，後者可更清楚說明行為 - 所有指標都已暫停。此外，由於 runWithMeasurementDisabled 函式是內嵌的，因此無法重新宣告該函式以開放存取權，因此請公開 MicrobenchmarkScope 超類別。(I9e23b、b/389149423、b/149979716)。
• 基準程式庫已遷移至 Kotlin 2.0。(I9d1e0)
• 已移除 androidx.benchmark.startupProfiles.enable 檢測引數。由於 BaselineProfileRule.collect() 中的 includeInStartupProfile arg 可控制這項功能，因此已不再實用。(I39eb4)

修正錯誤

• 減少剖析期間呼叫的 Microbenchmark 內部函式數量，以便更清楚顯示方法追蹤記錄 (Ifaed8)
• 針對當執行基準測試前無法停止背景 Perfetto 程序時，發生的錯誤進行推測修正：'Failed to stop [ProcessPid(processName=perfetto, pid=...)]'。現在，如果在執行基準測試前無法停止背景 Perfetto 程序，基準測試會記錄訊息，而不會發生錯誤。(I37d3e、b/323601788)。
• 修正因輸出格式檢查過於嚴格而導致的「Expected pm dump-profiles stdout」標籤問題。IllegalStateExceptions(I358dc)。

1.4.0-alpha07 版本

2025 年 1 月 29 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha07。1.4.0-alpha07 版包含這些修訂項目。

新功能

• BaselineProfileRule 現在推出 collectWithResults(...) API，其中包含計算設定檔的路徑清單。(I056f8)。
• 新增 androidx.benchmark.measureRepeatedOnMainThread.throwOnDeadline 檢測引數，可設為 false，以便在本機測試時停用 measureRepeatedOnMainThread 的逾時行為。不建議使用，因為這會增加測試期間發生 ANR 的可能性。(Idbeec、b/353226476)。

API 變更

• 已將 @JvmOverloads 新增至 MicrobenchmarkConfig 建構函式。(I13fd3)
• 重構 BenchmarkRule，以便建構於協同程式之上，並支援更佳的 yield() 行為。這項重構作業移除了幾個實驗性 BenchmarkState API，但會視需要進行替換。此外，我們也新增了 runWithMeasurementDisabled，以便說明行為 (所有評估都已暫停)。runWithTimingDisabled 日後將淘汰。(I19837、b/389149423、b/311242861)。
• 將 PerfettoTraceProcessor 移至新的 androidx.benchmark:benchmark-traceprocessor 構件中的 TraceProcessor，並將大部分 API 設為非實驗性質。任何自訂 TraceMetric 或從追蹤記錄讀取的任何內容都必須更新為新的 TraceProcessor 匯入項目。新的 TraceProcessor API 與舊版 API 運作方式完全相同，但它是獨立的介面程式庫 (類似於 Room 的 androidx.sqlite 層)，並在 Macrobenchmark 中內建 Android 專屬實作項目。新的構件也可以在 JVM 上使用，但目前您必須啟動自己的 TraceProcessor 二進位檔副本，並提供連線的連接埠。(I3a767、I62563、b/381134564)。

修正錯誤

• 當 MacrobenchmarkScope.startActivityAndWait 無法啟動目標程序 (可能因目標程序當機) 時，會顯示更明確的錯誤訊息，而非較模糊的「無法確認活動啟動完成」訊息 (I3539b)
• 修正 Kotlin 範例中的幾個語法錯誤，以及幾個 Java / build.gradle 範例中的語法醒目顯示。(Ib3808)
• 已清楚說明 ArtMetric 和 CaptureInfo 參數文件。(I96e60)。

1.4.0-alpha06 版本

2024 年 12 月 11 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha06。1.4.0-alpha06 版包含這些修訂項目。

API 變更

• 由於 Studio 的醒目顯示/剖析功能無法正常運作，因此已移除 PerfettoTraceProcessor.Session.query() 中的 @Language("sql") 用法。(Idc2fa、b/377733398)。

修正錯誤

• 這個程式庫現在使用 JSpecify 空值註解，這是類型用途。Kotlin 開發人員應使用下列編譯器引數，確保正確使用方式：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版起的預設值)。(I46810、b/326456246)。
• 修正 ArtMetric 以回報類別載入 (而非初始化)，並改善文件以說明執行階段行為。(I9915c)。
• 在 Android 多使用者模式中，請只在已解鎖的裝置上以 root 權限執行指令。(I88b44)。

1.4.0-alpha05 版

2024 年 11 月 13 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha05。1.4.0-alpha05 版包含這些修訂項目。

修正錯誤

• 修正 API 34 以上版本的問題，CompilationMode.None() 會出現不一致的效能，無法代表初始的、最糟的效能。這項變更可解決平台變更問題，讓 ART 的編譯狀態 verify 在首次啟動後不久便可部分編譯應用程式 (僅影響類別載入)。(Ie48d0)
• 修正了以下問題：由於 Perfetto 追蹤記錄中會截斷處理程序名稱，因此系統無法擷取 (尤其是短) 追蹤記錄，也無法從內建的 Macrobenchmark 指標回報測量值。如今，除了預期的套件名稱外，宏 Benchmark 也會在所有內建查詢中尋找經過截斷的套件名稱，以解決這個問題。請注意，自訂 TraceMetric 實作或其他 PerfettoSession.query 直接呼叫端可以透過變更 Perfetto 查詢中的 process.name LIKE "$packageName" 為 (process.name LIKE "$packageName" OR process.name LIKE "$(packageName.takeLast(15))")，實作相同的行為。(I5bf01、b/377565760)。

1.4.0-alpha04 版本

2024 年 10 月 30 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha04。1.4.0-alpha04 版包含這些修訂項目。

新功能

• (實驗功能) 啟用基準設定檔產生功能，並對安裝給次要使用者的應用程式進行基準測試，例如無頭 Android Auto 裝置上的任何應用程式。我們已在某些情境下測試這項支援功能，但如果無法正常運作，請向我們回報錯誤。(I9fcbe、b/356684617、b/373641155)

修正錯誤

• isProfileable 現在一律會在基準測試版本中覆寫，isDebuggable 也一律會在基準測試版本和 nonMinified (基準設定檔擷取) 版本中覆寫。(I487fa、b/369213505)。
• 修正 API 28 之前的部分實體裝置上的編譯偵測功能 - 影響 json context.compilationMode 和 androidx.benchmark.requireAot=true 的行為 (不再錯誤地擲回) (Ic3e08、b/374362482)
• 在 CpuEventCounter 指標中，如果觀察到無效的測量值 (例如 instructions/cpucycles==0)，就會擲回 (I8c503)

1.4.0-alpha03 版

2024 年 10 月 16 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha03。1.4.0-alpha03 版包含這些修訂版本。

API 變更

• Macrobenchmark：新增 ArtMetric，可用於檢查設定檔涵蓋率或一般 Android 執行階段效能。擷取 JIT、類別初始化 (如有) 和類別驗證的次數和總時間長度。此外，變更 CaptureInfo 以預設方式納入選用的 ART 主線版本。(I930f7)。
• 將 coefficientOfVariation 新增至基準測試 JSON 輸出內容，即可顯示特定基準測試執行期間的穩定性。(Ib14ea)

修正錯誤

• 修正 AVD 裝置中含有空格的 CollectBaselineProfileTask 問題。(Ia0225、b/371642809)。
• 針對 StartupMode.COLD 例外狀況的錯誤，使用推測修正：Package <packagename> must not be running prior to cold start!。如今，MacrobenchmarkScope.killProcess() (包括在每次迭代前執行的用於實作 StartupMode.COLD 行為的函式) 會等待驗證應用程式的程序是否已全部停止執行。(I60aa6、b/351582215)
• 修正部分已取得 root 權限的模擬器會顯示 UNLOCKED_ 錯誤的問題。(Ic5117)。
• 這個程式庫現在使用 JSpecify 空值註解，這是類型用途。Kotlin 開發人員應使用下列編譯器引數，確保正確使用方式：-Xjspecify-annotations=strict (這是 Kotlin 編譯器 2.1.0 版起的預設值)。(I7104f、b/326456246)。

1.4.0-alpha02 版

2024 年 10 月 2 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha02。1.4.0-alpha02 版包含這些修訂項目。

API 變更

• 將 Gradle 工作 lockClocks 和 unlockClocks 移至基準測試專案，而非在頂層提供。這項變更是必要的，因為如果不破壞專案隔離功能，就無法將這些項目註冊為頂層動作。(I02b8f、b/363325823)。

修正錯誤

• BaselineProfileRule 現可為多程序應用程式收集設定檔，方法是在區塊結尾時向每個執行程序發出信號，以便轉儲設定檔。如果以設定檔為基礎的編譯作業無法成功找到要廣播的程序，編譯作業就會失敗，因為設定檔中不應含有資料。此外，我們也新增了檢測引數，用於控制傾印等候時間：androidx.benchmark.saveProfileWaitMillis (I0f519、b/366231469)
• 來自基準測試 1.3.2：修正 Firebase Test Lab (FTL) 無法從基準設定檔 Gradle 外掛程式中提取基準設定檔或 Macrobenchmark 結果檔案的問題。(I2f678、b/285187547)。

如要使用 FTL，請將外掛程式套用至外掛程式區塊中的基準設定檔模組，並使用以下程式碼：

  plugins {
      ...
      id("com.google.firebase.testlab")
  }

然後使用以下設定來設定 Firebase Test Lab：

  firebaseTestLab {

      // Credentials for FTL service
      serviceAccountCredentials.set(file("credentials.json"))

      // Creates one or more managed devices to run the tests on.
      managedDevices {
          "ftlDeviceShiba34" {
              device = "shiba"
              apiLevel = 34
          }
      }

      // Ensures the baseline profile is pulled from the device.
      // Note that this will be automated as well later with aosp/3272935.
      testOptions {
          results {
              directoriesToPull.addAll("/storage/emulated/0/Android/media/${android.namespace}")
          }
      }
  }

此外，您也必須將建立的 FTL 裝置新增至基準設定檔擴充功能：

  baselineProfile {
      managedDevices += "ftlDeviceShiba34"
      useConnectedDevices = false
  }

1.4.0-alpha01 版

2024 年 9 月 18 日

發布 androidx.benchmark:benchmark-*:1.4.0-alpha01。1.4.0-alpha01 版包含這些修訂版本。

新功能 - 應用程式啟動深入分析

• 您可以在 Macrobenchmark 中啟用應用程式啟動初始版本的洞察資料。(09fae38)。

如要在啟動基準測試中啟用此功能，請按照下列步驟操作：

  @Test
  fun startup {
      macrobenchmarkRule.measureRepeated(
          …
          packageName = "com.example.my.application.id"
          metrics = listOf(StartupTimingMetric()),
          iterations = 5,
          startupMode = StartupMode.COLD,
          compilationMode = CompilationMode.None(),
          experimentalConfig = ExperimentalConfig(startupInsightsConfig = StartupInsightsConfig(isEnabled = true))
          ) {
          scope.startActivityAndWait(...)
      }
  }

接著，執行啟動基準測試會分析追蹤記錄，找出常見問題，並在基準測試分頁中，在指標後方列印這些問題，例如：

StartupBenchmark_startup[startup=COLD,compilationMode=None]
├── Metrics
│   ├──   timeToFullDisplayMs                min  1,147.2,   median  1,208.8,   max  1,307.4
│   └──   timeToInitialDisplayMs             min  1,147.2,   median  1,208.8,   max  1,307.4
├── App Startup Insights
│   ├── App in debuggable mode (expected: false)
│   │   └── seen in iterations: 0(true) 1(true) 2(true) 3(true) 4(true) 5(true) 6(true) 7(true) 8(true) 9(true)
│   ├── Potential CPU contention with another process (expected: < 100000000ns)
│   │   └── seen in iterations: 4(105022546ns)
│   └── Main Thread - Binder transactions blocked (expected: false)
│       └── seen in iterations: 7(true)
└── Traces
    └── Iteration 0 1 2 3 4 5 6 7 8 9

這項功能仍在開發中，我們會持續改善說明文件和可擴充性，但歡迎您提供意見回饋。

新功能

• 新增 Gradle 屬性 androidx.baselineprofile.suppressWarnings，以便抑制所有基準設定檔警告。(314153a)。
• Microbench 指標現在會以計數器的形式顯示在 Perfetto 追蹤記錄中。(3214854)。
• 新增實驗性指令碼，用於停用 JIT (需要 Root 權限 / 重新啟動執行階段)，以及重設裝置效能/測試狀態。這些目前不會以 Gradle 工作形式發布。(7c3732b)。
• 新增基準測試引數，在模擬器上執行時略過測試。啟用 automaticGenerationDuring 版本後，基準測試也會觸發基準設定檔產生作業。如果使用模擬器，這項操作就會失敗。我們可以使用新的引數 skipBenchmarksOnEmulator 略過測試。(0c2ddcd)。
• 變更效能事件啟用邏輯，以便在 API 23 以上版本上執行 (2550048)

API 變更

• 將 MacrobenchmarkRule.measureRepeated() 現有的實驗性 PerfettoConfig 引數移至新的 ExperimentalConfig 物件。

修正錯誤

• 增加 lockClocks.sh 重試次數 (99e9dac)
• 如果已存在 nonMinified 和基準建構類型，請勿建立這類類型。由於發生錯誤，即使 nonMinified 和基準建構類型已存在，仍會重新建立。(e75f0a5)。
• 忽略 TraceSectionMetric 結果中的非終止切片。(a927d20)
• 改善模擬器檢查功能，以考量 sdk_ 前置字串。(1587de8)
• 將未執行的套件視為已在 FrameTimingGfxInfoMetric 中清除。(35cc79c)
• 修正 androidx.benchmark.cpuEventCounter 為非指令事件產生損毀值的問題。(06edd59)。
• 修正 resumeTiming/runWithTimingDisabled，以便遵循指標優先順序，並大幅減少較低優先順序指標暫停/繼續播放對較高優先順序指標結果的影響。舉例來說，如果透過 cpuEventCounter.enable 檢測引數使用 CPU 效能計數器，則在發生暫停/繼續時，timeNs 就不會大幅減少。(5de0968)。

1.3 版本

1.3.4 版本

2025 年 3 月 26 日

發布 androidx.benchmark:benchmark-*:1.3.4。1.3.4 版包含這些修訂版本。

修正錯誤

• 修正基準 Gradle 外掛程式中 Gradle 專案隔離不相容的問題。(b/404523257)

1.3.3 版本

2024 年 10 月 16 日

發布 androidx.benchmark:benchmark-*:1.3.3。1.3.3 版包含這些修訂版本。

修正錯誤

• 修正 AVD 裝置有空格的 CollectBaselineProfileTask (Ia0225、b/371642809)

1.3.2 版

2024 年 10 月 2 日

發布 androidx.benchmark:benchmark-*:1.3.2。1.3.2 版包含這些修訂版本。

修正錯誤

• 修正 Firebase Test Lab (FTL) 無法從基準設定檔 Gradle 外掛程式中提取基準設定檔或 Macrobenchmark 結果檔案的問題。(I2f678、b/285187547)。

如要使用 FTL，請將外掛程式套用至外掛程式區塊中的基準設定檔模組，並使用以下程式碼：

  plugins {
      ...
      id("com.google.firebase.testlab")
  }

然後使用以下設定來設定 Firebase Test Lab：

  firebaseTestLab {

      // Credentials for FTL service
      serviceAccountCredentials.set(file("credentials.json"))

      // Creates one or more managed devices to run the tests on.
      managedDevices {
          "ftlDeviceShiba34" {
              device = "shiba"
              apiLevel = 34
          }
      }

      // Ensures the baseline profile is pulled from the device.
      // Note that this will be automated as well later with aosp/3272935.
      testOptions {
          results {
              directoriesToPull.addAll("/storage/emulated/0/Android/media/${android.namespace}")
          }
      }
  }

此外，您也必須將建立的 FTL 裝置新增至基準設定檔擴充功能：

  baselineProfile {
      managedDevices += "ftlDeviceShiba34"
      useConnectedDevices = false
  }

1.3.1 版本

2024 年 9 月 18 日

發布 androidx.benchmark:benchmark-*:1.3.1。1.3.1 版包含這些修訂項目。

修正錯誤

• 新增 Gradle 屬性 androidx.baselineprofile.suppressWarnings，用於抑制所有基準設定檔警告 (I7c36e、b/349646646)
• 修正基準設定檔 Gradle 外掛程式，以便在應用程式建立時使用預先存在的 nonMinified… 和 benchmark…，而非建立包裝函式。(Ia8934、b/361370179)。
• 修正在模擬器上啟用 automaticGenerationDuringBuild 時發生的 java.lang.AssertionError: ERRORS (not suppressed): EMULATOR 問題。改用新引數來略過測試。(If3f51、b/355515798)。
• Microbenchmark 精簡 - 在基準測試程式庫 proguard 中保留 org.junit.runner.notification.RunListener 的子類別 (Ic8ed5、b/354264743)
• 修正 TraceSectionMetric，以便忽略非終止切片。以往這些事件會被視為有 -1 的時間長度，例如在加總或找出最短時間長度時。(If74b7)
• 修正 FrameTimingGfxInfoMetric 中的問題，如果處理程序尚未執行，啟動指標就會停止運作。(I6e412)

1.3.0 版本

2024 年 8 月 21 日

發布 androidx.benchmark:benchmark-*:1.3.0。1.3.0 版包含這些修訂版本。

自 1.2.0 版以來的 Microbenchmark 異動

• 在大多數裝置上執行時，微型基準測試預設會啟用方法追蹤功能
  • 方法追蹤會在測量後以個別階段執行，這樣一來，單一基準測試執行作業就能輸出準確的測量結果和方法追蹤記錄
  • 部分 Android 作業系統和 ART 版本上的程式追蹤功能會影響後續的評估階段 - 在這些版本中，程式追蹤功能預設為關閉，且會在 Studio 輸出內容中顯示警告
• 主要執行緒基準測試和 ANR
  • 為 UI 執行緒基準測試 (例如與 Compose/View UI 互動的執行緒) 新增 measureRepeatedOnMainThread，以便在執行數秒後避免 ANR。
  • 如果方法追蹤記錄預計會超過 ANR 避免期限，系統會略過這些追蹤記錄。將 androidx.benchmark.profiling.skipWhenDurationRisksAnr 設為 false 即可停用這項行為 (不建議在持續整合執行作業中使用，因為在長時間的持續整合執行作業中，ANR 可能會導致問題)。
• 壓縮
  • 嵌入 ProGuard 規則，在啟用壓縮功能時改善微型基準測試
  • 程式庫模組中的縮減/R8 功能需要 AGP 8.3，可透過 build.gradle 中的 android.buildTypes.release.androidTest.enableMinification 啟用
  • 新增實驗性 BlackHole.consume() API，以免淘汰無效程式碼 (If6812、b/286091643)
• 指標
  • 實驗性 CPU 事件計數器功能 (來自 perf_event_open 的指標，在大多數平台版本上都需要取得 root 權限)，可透過 InstrumentationArgument androidx.benchmark.cpuEventCounter.enable 存取 (可設為 true)，而 androidx.benchmark.cpuEventCounter.events 可設為 (Instructions,CpuCycles)。這項功能應可在部分 userdebug 模擬器上支援，但尚未在所有可用的模擬器上測試支援性

自 1.2.0 版以來的 MACRObenchmark 異動

• 為 Macrobenchmark 改善方法追蹤功能。
  • 方法追蹤記錄的範圍現在限於 measureBlock 的時間長度，如果程序啟動多次，則可擷取多個工作階段。
  • 先前，方法追蹤功能只適用於 StartupMode.COLD 基準測試，且不會擷取未重新啟動目標程序的 measureBlocks 資料
  • 修正宏觀基準測試中的清除方法追蹤記錄問題，以便在較慢的裝置上完整擷取並驗證方法追蹤記錄。(I6349a、b/329904950)。
• 在程序終止時，在個別 warmUp 迭代期間正確轉儲 ART 設定檔，以便 CompilationMode.Partial(warmup=N) 測量結果更準確。(I17923)
• 丟棄著色器廣播失敗訊息
  • 新增偵錯建議，以便捨棄著色器廣播失敗訊息
  • 新增兩個檢測引數，用於覆寫著色器捨棄行為，以便在未使用 ProfileInstaller 1.3 的應用程式進行基準測試時解決當機問題：
    • androidx.benchmark.dropShaders.enable=true/false：可用於略過所有著色器捨棄作業 (包括在 StartupMode.Cold 啟動時執行的作業)，特別是在基準測試尚未使用 ProfileInstaller 1.3 的應用程式時
    • androidx.benchmark.dropShaders.throwOnFailure=true/false：可用於在嘗試捨棄著色器時容許失敗，例如在沒有 ProfileInstaller 1.3 (I4f573) 的情況下對應用程式進行基準測試時
• 新增實驗性 MacrobenchmarkRule#measureRepeated 變化版本，可使用自訂 PerfettoConfig 進行完全自訂的 Perfetto 追蹤記錄。請注意，設定錯誤的設定可能會導致內建的指標類別失敗。(Idfd3d、b/309841164、b/304038384)。
• 請在執行 Macrobenchmark 之前取消背景 dexopt 工作，以減少干擾。(I989ed)
• Macrobenchmark 現在會等待 1 秒，讓目標應用程式將 ART 設定檔刷新 (先前為 500 毫秒)。(I85a50、b/316082056)
• TraceSectionMetric 全面改造
  • 注意：TraceSectionMetric下列變更可能會影響 CI 用途的輸出內容，並可能造成不連續或中斷剖析
  • 目前預設值為總和，因為這項指標多半用於重複事件，在這種情況下，先會捨棄資料
  • 變更為更具客製化功能，並提供更多可用模式
  • 模式名稱現在已嵌入指標輸出名稱 (在 Studio 和 JSON 中)
  • 現已支援使用 Trace.{begin|end}AsyncSection 建立的切片。
• 指標
  • 電源 - 已新增 PowerMetric.deviceSupportsHighPrecisionTracking、PowerMetric.deviceBatteryHasMinimumCharge() 和 PowerMetric.deviceSupportsPowerEnergy()
  • 將 Metric.getResult 重新命名為 getMeasurements，以符合傳回類型
  • 在所有啟動偵測失敗中新增 log.w / 例外狀況標籤。這不會變更目前的行為 (因此會擲回某些錯誤，而其他錯誤則會在啟動時悄悄失敗)，只是讓這項行為更容易理解。通常，如果 Log.w() 且無法回報啟動指標，表示缺少非影格事件，在偵測到啟動時會擲回例外狀況，但影格時間資訊 (來自 UI/RT 切片) 除外。(Id240f、b/329145809)。
  • 我們已將 frameCount 評估值新增至 FrameTimingMetric，協助找出因產生影格數量變動 (新增動畫、修正失效問題) 而導致評估值變更的情況。(I1e5aa)。
  • 說明 frameOverrunMs 是 Google 文件中可用來追蹤的首選指標，並說明原因。(I18749、b/329478323)
  • 修正問題：追蹤記錄的開頭和結尾可能會配對未結束的畫面，導致系統誤報為單一極長的畫面。(I39353、b/322232828)。
  • 改善未產生影格時的 FrameTimingMetric 錯誤，並在無法剖析成效指標時一律輸出追蹤連結，以利診斷問題。(I956b9)。
  • 修正 FrameTimingMetric 無法剖析影格 ID 的異常終止問題，尤其是在特定 OEM 裝置上。(Ia24bc、b/303823815、b/306235276)。
  • 放寬 FrameMetrics 中的檢查嚴格度，並在錯誤訊息中加入更多詳細資訊。(Iadede)。

自 1.2.0 版以來的基準設定檔擷取 / Gradle 外掛程式異動

• 將建議使用的最高 AGP 版本提高至 9.0.0-alpha01。
• 請務必確保 mergeArtProfile 和 mergeStartupProfile 工作一律等待基準設定檔產生。(I623d6、b/343086054)。
• 成功產生基準設定檔後，系統會輸出變更內容摘要 (I824c8、b/269484510)
• 新增 DSL 來停用警告 (Ic4deb、b/331237001)
• 修正問題，確保基準在 automaticGenerationDuringBuild 關閉時使用產生的基準設定檔 (Ic144f、b/333024280)
• 修正 BaselineProfile Gradle 外掛程式屬性覆寫值，以便在自訂 nonMinified 或基準測試建構類型時，啟用基準設定檔產生和基準測試功能。(Ib8f05、b/324837887)
• 修正在 AGP 8.3.0-alpha15 之前的 AAR 中加入程式庫基準設定檔的問題。(I1d2af、b/313992099)。
• 修正產生工作結束時的基準和啟動設定檔輸出網址。(I802e5、b/313976958)。

自 1.2.0 版以來的其他重大異動

• 追蹤記錄擷取
  • 從錯誤到記錄警告，減少啟動 Perfetto 時發生的 EXITCODE 2 錯誤
  • 在基準測試中預設啟用 AIDL 追蹤功能(需要 API 28) (Ia0af2、b/341852305)
  • 在基準測試中預設啟用 porter 標記追蹤功能。例如，這項功能可擷取喚醒鎖定追蹤點。(Icfe44、b/286551983)。
  • 增加追蹤記錄擷取開始逾時時間，以免在較慢的裝置上開始追蹤時發生當機問題 (I98841、b/329145808)
  • 新增了使用 JSON、textproto 和 proto 二進位檔 (未解碼) 變化版本的公開 API PerfettoTraceProcessor.Session.queryMetrics。這些指標可讓您查詢 TraceProcessor 中內建的指標 (I54d7f、b/304038382)
  • 啟用 Perfetto 追蹤記錄的阻斷啟動功能，降低追蹤記錄開始時遺漏資料的風險。僅支援 API 33 以上版本。(Ie6e41、b/310760059)
• JSON 輸出內容
  • 在 JSON 輸出的基準測試內容中新增其他資訊：
    • context.artMainlineVersion - Art 主線模組的整數版本 (如果裝置上有此模組，否則為 -1)
    • context.build.id - 等於 android.os.Build.ID
    • context.build.version.codename - 等於 android.os.Build.VERSION.CODENAME
    • context.build.version.abbreviatedCodename - 對應至預先發布版程式碼名稱 (包括發布版本) 的首字母 (Ie5020)
  • 將 profilerOutput 清單新增至 JSON 輸出內容，方便使用追蹤記錄 (例如 Perfetto、方法追蹤記錄) 的工具 (I05ddd、b/332604449)
  • 在基準模組中使用 Android Test Orchestrator 時，系統會新增警告，因為這會導致重複覆寫每個模組的輸出 JSON 檔案。(Ia1af6、b/286899049)。
  • 當檔案名稱超過 200 個字元時，系統會擲回錯誤，以避免在寫入或後置處理檔案時發生不明的當機情形。(I4a5ab)。

1.3.0-rc01 版本

2024 年 8 月 7 日

發布 androidx.benchmark:benchmark-*:1.3.0-rc01。1.3.0-rc01 版本包含這些修訂版本。

修正錯誤

• 修正 androidx.benchmark.cpuEventCounter 為非指令事件產生損毀值的問題 (I7386a、b/286306579)
• 修正 resumeTiming/runWithTimingDisabled，以便遵循指標優先順序，並大幅減少較低優先順序指標暫停/繼續播放對較高優先順序指標結果的影響。舉例來說，如果透過 cpuEventCounter.enable 檢測引數使用 CPU 效能計數器，則在發生暫停/繼續時，timeNs 就不會大幅減少。(I39c2e、b/286306579、b/307445225)。
• 將堆疊取樣轉換作業從主執行緒移出，減少堆疊取樣導致 measureRepeatedOnMainThread 觸及主執行緒硬性逾時的機率。(I487a8、b/342237318)。
• 移除新平台 API 存取權的手動設定，因為在使用 AGP 7.3 以上版本 (例如 R8 3.3 版) 的 R8 時，以及在使用 AGP 8.1 以上版本 (例如 D8 8.1 版) 的所有版本時，系統會透過 API 模擬功能自動執行此操作。建議未使用 AGP 的用戶端更新至 D8 8.1 以上版本。詳情請參閱這篇文章。(I9496c、b/345472586)。
• 新增 agp 版本檢查，以便將套件名稱做為 instr arg 傳送。在 AGP 8.4.0 之前，無法透過檢測設備引數將目標應用程式套件名稱傳送至檢測設備應用程式。(0c72a3f)

1.3.0-beta02 版

2024 年 7 月 10 日

發布 androidx.benchmark:benchmark-*:1.3.0-beta02。1.3.0-beta02 版包含這些修訂項目。

修正錯誤

• 啟動 Perfetto 時，請妥善處理 EXITCODE 2 以記錄警告，但繼續執行。

1.3.0-beta01 版本

2024 年 6 月 12 日

發布 androidx.benchmark:benchmark-*:1.3.0-beta01。1.3.0-beta01 版包含這些修訂版本。

API 變更

• 為求一致，請將 MethodTracing.affectsMeasurementOnThisDevice 重新命名為 AFFECTS_MEASUREMENT_ON_THIS_DEVICE。(I1bdfa)
• 新增實驗性 BlackHole.consume() API，以避免在微型基準測試中淘汰無效程式碼。(If6812、b/286091643)
• Microbenchmark 現可正確擲回，以免方法追蹤干擾測量。在某些裝置上，如果強制啟用方法追蹤功能 (透過檢測設備引數或 MicrobenchmarkConfig)，並在方法追蹤後嘗試評估，就會發生這種情況。受影響的裝置執行的是 API 26 至 30 或特定 ART 主線模組版本，且受到這項干擾影響，可在執行階段透過 ProfilerConfig.MethodTracing.affectsMeasurementOnThisDevice 偵測。(Iafb92、b/303660864)。

修正錯誤

• 建議將推薦的最高 AGP 版本調升至 9.0.0-alpha01。(I5bbb0)。
• 在基準測試內容中新增編譯模式 (If5612、b/325512900)
• 預設啟用 AIDL 追蹤功能 (需要 API 28) (Ia0af2、b/341852305)
• 在 JSON 輸出的基準測試內容中新增其他資訊：
  • context.artMainlineVersion - Art 主線模組的整數版本 (如果裝置上有此模組，則為 -1)
  • context.build.id - 等於 android.os.Build.ID
  • context.build.version.codename - 等於 android.os.Build.VERSION.CODENAME
  • context.build.version.abbreviatedCodename - 對應至預先發布版程式碼名稱的首字母 (即使是在發布版本中) (Ie5020)
• 修正 StackSampling，以便尊重 androidx.benchmark.profiling.sampleDurationSeconds (Ib1d53)
• 將 macro->common dependency 變更為 api()，方便使用 PerfettoTrace 和 PerfettoConfig 等。(Icdae3、b/341851833)。
• 請務必確保 mergeArtProfile 和 mergeStartupProfile 工作一律等待基準設定檔產生。(I623d6、b/343086054)。
• 決定是否要啟用變化版本時，請考量變化版本的啟用狀態。(I5d19e、b/343249144)。
• 增加了 Perfetto 追蹤記錄處理工具的預設啟動逾時時間。(I87e8c、b/329145808)。

1.3.0-alpha05 版

2024 年 5 月 14 日

發布 androidx.benchmark:benchmark-*:1.3.0-alpha05。1.3.0-alpha05 版包含這些修訂項目。

修正錯誤

• 在 macrobench 指標為所有迭代作業傳回零值時，擲回更明確的例外狀況 (Iab58f、b/314931695)
• 在 microbench ProGuard 規則中新增其他因應規則，包括支援事件監聽器規則和其他觀察到的警告 / 錯誤。(I14d8f、b/329126308、b/339085669)。
• 方法追蹤會在 Macrobenchmark 期間以獨立階段執行，且不會再影響測量。(If9a50、b/285912360、b/336588271)。
• 新增額外的偵錯建議，以便刪除著色器廣播失敗訊息。(I5efa6、b/325502725)。

1.3.0-alpha04 版本

2024 年 5 月 1 日

發布 androidx.benchmark:benchmark-*:1.3.0-alpha04。1.3.0-alpha04 版包含這些修訂項目。

API 變更

• 新增實驗性 MacrobenchmarkRule#measureRepeated 變化版本，可使用自訂 PerfettoConfig 進行完全自訂的 Perfetto 追蹤記錄。請注意，設定錯誤的設定可能會導致內建的指標類別失敗。(Idfd3d、b/309841164、b/304038384)。
• 將 PowerMetric.deviceSupportsPowerEnergy 重新命名為 PowerMetric.deviceSupportsHighPrecisionTracking，以便清楚理解 (I5b82f)
• 新增 PowerMetric.deviceBatteryHasMinimumCharge() 和 PowerMetric.deviceSupportsPowerEnergy()，可根據裝置的電力測量能力變更或略過基準。(I6a591、b/322121218)。

修正錯誤

• 新增與先前基準設定檔的比較 (I824c8、b/269484510)
• 新增 DSL 來停用警告 (Ic4deb、b/331237001)
• 在停用基準測試變化版本時，將例外狀況變更為資訊記錄 (I8a517、b/332772491)
• 為了簡化 Macrobenchmark 方法追蹤記錄的擷取作業，其範圍將限於實際 measureBlock() 的時間長度。先前，這個服務會在目標程序啟動時啟動，且只支援冷啟動 (Iee85a、b/300651094)
• 避免在 Perfetto 追蹤處理器啟動速度緩慢時發生當機問題 (I98841、b/329145808)

1.3.0-alpha03 版

2024 年 4 月 17 日

發布 androidx.benchmark:benchmark-*:1.3.0-alpha03。1.3.0-alpha03 版包含這些修訂版本。

新功能

• 新增含有 JSON、textproto 和 proto 二進位檔 (未解碼) 變化版本的公開 API PerfettoTraceProcessor.Session.queryMetrics。這些指令可讓您查詢 TraceProcessor 內建的指標 (I54d7f、b/304038382)
• 在 JSON 輸出內容中新增 profilerOutput，方便使用剖析追蹤記錄的工具 (例如 perfetto、方法追蹤記錄)。(I05ddd、b/332604449)。
• 在基準 Perfetto 設定中新增電源標記。例如，這項功能可擷取喚醒鎖定追蹤點。(Icfe44、b/286551983)。
• 新增的 inst 引數 androidx.benchmark.profiling.skipWhenDurationRisksAnr 可設為 false，以避免在預期時間可能導致 ANR 時略過方法追蹤記錄，強烈建議在 CI 執行作業中避免這類情況。
• 新增實驗性 inst 引數 androidx.benchmark.profiling.perfCompare.enable，將其設為 true 即可在評估和剖析階段之間執行比較時間。例如，評估方法追蹤的額外負擔時，就很實用。(I61fb4、b/329146942)。

API 變更

• 將 TraceSectionMetric.Mode 變更為密封類別，以便日後擴充，且不會破壞完整的 when 陳述式 (I71f7b)
• 新增 TraceSectionMetric.Mode.Average 和 .Count，並重新排序引數，讓較常見的引數 (模式) 出現在引數清單的前面，減少指定參數名稱的需求。(Ibf0b0、b/315830077、b/322167531)。
• Metric.getResult 已重新命名為 getMeasurements，以符合傳回類型 (I42595)

修正錯誤

• 修正問題，確保基準在 automaticGenerationDuringBuild 關閉時使用產生的基準設定檔 (Ic144f、b/333024280)
• 修正 BaselineProfile Gradle 外掛程式屬性覆寫值，以便在自訂 nonMinified 或基準測試建構類型時，啟用基準設定檔產生和基準測試功能。(Ib8f05、b/324837887)
• 修正宏觀基準測試中的清除方法追蹤記錄問題，以便在較慢的裝置上完整擷取並驗證方法追蹤記錄。(I6349a、b/329904950)。
• 啟用 Perfetto 追蹤記錄的阻斷啟動功能，降低追蹤記錄開始時遺漏資料的風險。僅支援 API 33 以上版本。(Ie6e41、b/310760059)
• 在基準模組中使用 Android Test Orchestrator 時，系統會新增警告，因為這會導致重複覆寫每個模組的輸出 JSON 檔案。(Ia1af6、b/286899049)。
• 強制使用「,」(逗號) 做為 Studio 輸出內容中的千位數分隔符，忽略裝置語言代碼 (I3e921、b/313496656)
• TraceSectionMetric 現在支援使用 Trace.{begin|end}AsyncSection 建立的切片。(I91b32、b/300434906)
• 在所有啟動偵測失敗中新增 log.w / 例外狀況標籤。這不會變更目前的行為 (因此會擲回某些錯誤，而其他錯誤則會在啟動時悄悄失敗)，只是讓這項行為更容易理解。通常，如果 Log.w() 且無法回報啟動指標，表示缺少非影格事件，在偵測到啟動時會擲回例外狀況，但影格時間資訊 (來自 UI/RT 切片) 除外。(Id240f、b/329145809)。
• 請在執行 Macrobenchmark 之前取消背景 dexopt 工作，以減少干擾。(I989ed)
• 我們已將 frameCount 評估值新增至 FrameTimingMetric，協助找出因產生影格數量變動 (新增動畫、修正失效問題) 而導致評估值變更的情況。(I1e5aa)。
• 說明 frameOverrunMs 是 Google 文件中可用來追蹤的首選指標，並說明原因。(I18749、b/329478323)

1.3.0-alpha02 版本

March 20, 2024

發布 androidx.benchmark:benchmark-*:1.3.0-alpha02。1.3.0-alpha02 版包含這些修訂項目。

新功能

• 透過內嵌 ProGuard 規則，在 microbench 中提供實驗性 R8 支援。請注意，這項支援功能處於實驗階段，且需要使用 AGP 8.3 才能壓縮程式庫模組測試。請使用以下方式在基準模組的 build.gradle 中啟用 R8 縮減/最佳化功能，這應該會大幅提升效能 (視工作負載而定)。(I738a3、b/184378053)。

  android {
      buildTypes.release.androidTest.enableMinification = true
  }
  

修正錯誤

• 修正方法追蹤警告，使其與微型基準輸出內容位於不同行。(I0455c、b/328308833)。

1.3.0-alpha01 版本

2024 年 2 月 21 日

發布 androidx.benchmark:benchmark-*:1.3.0-alpha01。查看 1.3.0-alpha01 版的修訂項目。

API 變更

• 重新命名 MicrobenchmarkConfig 布林值參數，以免出現不必要的字詞「should」(Ia8f00、b/303387299)
• 新增 BenchmarkRule.measureRepeatedOnMainThread，讓主執行緒基準測試 (例如涉及 View 或 Compose UI 的測試) 避免觸發 ANR，特別是在 CI 中的大型套件期間。(I5c86d)。
• 新增 FrameTimingGfxInfoMetric，這是 FrameTimingMetric 的實驗性替代實作，可直接從平台取得測量資料，而非從 Perfetto 追蹤記錄中擷取。(I457cb、b/322232828)。
• 新增在個別 warmUp 迭代期間轉儲 ART 設定檔的功能。(I17923)
• TraceSectionMetric API 的幾項變更：
  • 新增 Mode.Min、Mode.Max
  • 新增標籤引數，將區段名稱覆寫為指標標籤
  • 新增模式名稱以便輸出，以便說明指標的含義
  • 由於這項指標多半用於重複事件，因此我們將預設值改為總和。請留意 CI 使用情況的變更，因為這可能會造成不連續或中斷剖析。(Ic1e82、b/301892382、b/301955938)。

修正錯誤

• 當指定的受管理裝置不存在時，基準設定檔 Gradle 外掛程式中的錯誤訊息已改善 (Idea2b、b/313803289)
• 修正在 AGP 8.3.0-alpha15 之前的 AAR 中加入程式庫基準設定檔的問題 (I1d2af、b/313992099)
• 修正產生工作結束時的基準和啟動設定檔輸出網址 (I802e5、b/313976958)
• 調整資料來源逾時時間，以便嘗試修正 java.lang.IllegalStateException: Failed to stop [ProcessPid(processName=perfetto, pid=...)] (I8dc7d、b/323601788)
• 新增兩個檢測引數，用於覆寫著色器捨棄行為，以便在未使用 ProfileInstaller 1.3 的應用程式進行基準測試時解決當機問題：
  • androidx.benchmark.dropShaders.enable=true/false：可用於略過所有著色器捨棄作業 (包括在 StartupMode.Cold 啟動時執行的作業)，特別是在基準測試尚未使用 ProfileInstaller 1.3 的應用程式時
  • androidx.benchmark.dropShaders.throwOnFailure=true/false：可用於在嘗試捨棄著色器時容許失敗，例如在沒有 ProfileInstaller 1.3 (I4f573) 的情況下對應用程式進行基準測試時
• 當預期在 UI 執行緒上執行的方法追蹤作業需要花費超過幾秒的時間，以及在擲回時清理方法追蹤時，請略過該作業。(I6e768)
• 當檔案名稱超過 200 個字元時，系統會擲回錯誤，以避免在寫入或後置處理檔案時發生不明的當機情形。(I4a5ab)。
• 修正問題：追蹤記錄的開頭和結尾可能會配對未結束的畫面，導致系統誤報為單一極長的畫面。(I39353、b/322232828)。
• 在 API 30-33 上重新安裝套件時，請在 API 30 以上版本上使用 --skip verification，以便在使用者版本中清除 ART 設定檔。這有助於略過 Play 安全防護警告，避免在某些類型的裝置上發生失敗。(Ic9e36)。
• 如非系統應用程式 (例如系統 UI 或啟動器)，請使用 am force-stop 終止應用程式。(I5e028)
• Macrobenchmark 現在會等待 1 second，讓目標應用程式刷新 ART 設定檔 (先前會等待 500 ms)。 (I85a50、b/316082056)
• 改善未產生影格時的 FrameTimingMetric 錯誤，並在無法剖析成效指標時一律輸出追蹤連結，以利診斷問題。(I956b9)。
• 修正 FrameTimingMetric 無法剖析影格 ID 的異常終止問題，尤其是在特定 OEM 裝置上。(Ia24bc、b/303823815、b/306235276)。
• 放寬 FrameMetrics 中的檢查嚴格度，並在錯誤訊息中加入更多詳細資訊。(Iadede)。

1.2 版本

1.2.4 版本

2024 年 4 月 17 日

發布 androidx.benchmark:benchmark-*:1.2.4。1.2.4 版包含這些修訂項目。

修正錯誤

• 修正基準設定檔在基準變化版本中未設定的 srcset。並修正程式庫中導致循環依附元件的 automaticGenerationDuringBuild。(I28ab7、b/333024280)。
• 如非系統應用程式 (例如系統 UI 或啟動器)，請使用 am force-stop 終止應用程式。這可修正 StartupMode.COLD 基準測試因程序終止未完全成功而發生的錯誤：「Package $package must not be running prior to cold start!」(I5e028)

1.2.3 版

2024 年 1 月 24 日

發布 androidx.benchmark:benchmark-*:1.2.3。1.2.3 版本包含以下修訂項目。

修正錯誤

• 當 AGP 版本為 8.3.0 以上時，從基準設定檔 Gradle 外掛程式中移除例外狀況。
• 修正在 AGP 8.3.0-alpha15 之前的 AAR 中加入程式庫基準設定檔的問題。

1.2.2 版本

2023 年 12 月 1 日

發布 androidx.benchmark:benchmark-*:1.2.2。1.2.2 版包含以下修訂項目。

基準設定檔

• 執行記錄會將基準設定檔輸出檔案路徑顯示為本機檔案 URI (aosp/2843918、aosp/2853665、b/313976958)

1.2.1 版本

2023 年 11 月 15 日

發布 androidx.benchmark:benchmark-*:1.2.1。查看 1.2.1 版的修訂項目。

新功能

• 改善使用者停用測試變化版本時的錯誤訊息 (b/307478189)
• 新增屬性以支援 AS 測試執行整合 (b/309805233)、(b/309116324)

1.2.0 版本

2023 年 10 月 18 日

發布 androidx.benchmark:benchmark-*:1.2.0。1.2.0 版包含此連結所列的修訂項目。

自 1.1.0 版以來的重要異動

基準設定檔

• 新的基準設定檔 Gradle 外掛程式可自動擷取基準設定檔，並將其納入測試和建構工作流程中。
• BaselineProfileRule.collect 現已穩定，這是先前實驗性 BaselineProfileRule.collectBaselineProfile API 的簡化版
  • 只要指定 packageName，即可驅動應用程式
• 對於產生基準設定檔的程式庫，您現在可以篩選程式碼 (BaselineProfileRule.collect 引數) 或 Gradle 外掛程式中產生的規則，甚至可以更簡單地篩選
• 修正項目
  • 修正 Android U+ 上的基準設定檔收集 (Id1392、b/277645214)

Macrobenchmark

• 編譯
  • Macrobenchmark 現在會正確地完全重設每項編譯作業的編譯狀態，這項作業需要在 Android 14 以下版本中重新安裝 APK，因此如果您想在測量項目中保留狀態 (例如使用者登入)，強烈建議您在 Android 14 以上版本中進行基準測試。
  • 您也可以分別控制應用程式編譯作業，並使用 CompilationMode.Ignore() 或檢測引數略過編譯作業。

• 檢測引數

  • 支援 androidx.benchmark.dryRunMode.enable 檢測引數 (已在微型基準測試中推出)，可加快驗證執行作業 (例如建立基準測試或在預先提交時)
  • 支援 androidx.benchmark.profiling.mode=StackSampling 和 MethodTracing。
  • 新增 androidx.benchmark.enabledRules，讓執行階段篩選基準設定檔與巨集基準規則測試
  • 新增 androidx.benchmark.perfettoSdkTracing.enable 引數，啟用追蹤-perfetto 追蹤功能，例如 Compose 重新組合追蹤。請注意，如果與 StartupMode.COLD 搭配使用，由於追蹤程式庫會在應用程式啟動期間載入及啟用，因此時間會受到重大影響。

• 需求條件

  • Macrobenchmark 目前需要在目標應用程式中使用 ProfileInstaller 1.3.0 以上版本，才能啟用設定檔擷取 / 重設功能，以及清除著色器快取內容。

• 全新實驗性指標 API

  • 新增實驗性 TraceSectionMetric，可從應用程式中的 trace("") {} 區塊擷取簡單的時間資訊，或使用 TraceMetric 來運用 Perfetto TraceProcessor 的完整查詢功能。
  • 新增實驗版 PowerMetric，用於擷取電力使用資訊
  • 新增實驗性 MemoryCountersMetric 來計算頁面錯誤
  • 新增了實驗性 PerfettoTraceProcessor API，用於在內部從系統追蹤記錄 (又稱為 Perfetto 追蹤記錄) 中擷取指標

• 修正項目

  • 修正在從多個 APK (例如應用程式套件) 安裝的應用程式中，安裝或擷取設定檔時發生異常終止的問題。
  • 修正 FrameTimingMetric 忽略具有不一致影格 ID 的影格 (通常是 API 31 以上版本的漣漪期間影格) (I747d2、b/279088460)
  • 修正追蹤記錄檔案大小超過 64 MB 時的剖析錯誤 (Ief831、b/269949822)
  • 在裝置 (尤其是模擬器) OS 映像檔未正確設定追蹤或編譯時，會顯示清楚的錯誤
  • 略過無電池裝置 (微型和宏觀) 的電池電量檢查
  • 改善檔案輸出功能，針對無效的輸出目錄提供更明確的錯誤訊息，並提供更安全的預設值
  • 透過持續捨棄著色器快取 (也透過 MacrobenchmarkScope.dropShaderCache 公開)，改善 StartupMode.COLD 的穩定性
  • 修正 startActivityAndWait 的 Leanback 備用廣告。

Microbenchmark

• 功能
  • 剖析作業已移至其他指標之後的獨立階段，因此單次測試執行作業可同時顯示準確的時間和剖析結果。
• 實驗性 API
  • 新增實驗性 MicrobenchmarkConfig API，用於定義自訂指標，以及設定追蹤和分析。可用於擷取方法追蹤記錄，或擷取追蹤點 (但請注意追蹤記錄的額外負擔)。
  • 新增實驗性 API，可在沒有 JUnit 的情況下，從 BenchmarkRule 單獨控制 BenchmarkState
  • 新增實驗性 PerfettoTrace 記錄，可透過自訂設定擷取 Perfetto 追蹤記錄，與基準測試 API 分開。
• 修正項目
  • 解決 Android Studio 基準測試輸出內容缺少前導空格的情況。
  • 修正 Android Studio 基準測試輸出內容中警告可能無法列印的問題。
  • 修正 Android 13 (API 33) 以上版本的 SampledProfiling 當機問題。
  • 略過 IsolationActivity 和 Perfetto 追蹤，大幅改善 dryRunMode 的效能 (在舊版 OS 上，模擬執行模式的速度可加快至 10 倍)。

1.2.0-rc02 版本

2023 年 10 月 6 日

發布 androidx.benchmark:benchmark-*:1.2.0-rc02。查看 1.2.0-rc02 版的修訂項。

修正錯誤

• 修正基準檔案輸出內容，以免影響 BaselineProfile 外掛程式檔案的複製作業。檔案已產生並複製到裝置外，但已重新命名，因此 Gradle 外掛程式無法看到這些檔案。(I8dbcc、b/303034735、b/296453339)
• 在從巨集基準模組注入至目標應用程式時，澄清 tracing-perfetto 載入錯誤訊息。

1.2.0-rc01 版本

2023 年 9 月 20 日

發布 androidx.benchmark:benchmark-*:1.2.0-rc01。查看 1.2.0-rc01 版的修訂項目。

修正錯誤

• Perfetto SDK 追蹤功能無法在基準測試中初始化時，現在會擲回例外狀況 (附上修正說明)。(I6c878、b/286228781)。
• 修正轉換 ART 方法追蹤記錄至 Perfetto 格式時發生的 OOM 當機問題。(I106bd、b/296905344)
• (Macrobenchmark) 在 Studio 測試輸出內容中連結時，已釐清方法追蹤標籤，並修正方法追蹤檔案名稱，使其在裝置/主機上保持不重複，因此在執行多個基準測試時，這些檔案就不會遭到覆寫。(I08e65、b/285912360)
• 確保在擷取基準設定檔時，裝置處於喚醒狀態。(I503fc)。

1.2.0-beta05 版

2023 年 8 月 30 日

發布 androidx.benchmark:benchmark-*:1.2.0-beta05。1.2.0-beta05 版包含以下修訂版本。

新功能

• 基準設定檔 Gradle 外掛程式現在支援 Android Gradle 外掛程式 8.3。(aosp/2715214)

1.2.0-beta04 版

2023 年 8 月 23 日

發布 androidx.benchmark:benchmark-*:1.2.0-beta04。1.2.0-beta04 版包含以下修訂項目。

新功能

• 基準設定檔 Gradle 外掛程式現在支援 Android Gradle 外掛程式 8.3。(aosp/2715214)

修正錯誤

• 進一步清理輸出檔案名稱，避免輸出檔案名稱中出現「=」和「:」，以修正寫入 / 移動和提取檔案 (尤其是參數化測試的檔案) 時發生的失敗問題。(I759d8)

1.2.0-beta03 版本

2023 年 8 月 9 日

發布 androidx.benchmark:benchmark-*:1.2.0-beta03。查看 1.2.0-beta03 版的修訂項目。

API 變更

• 新增引數，將 TraceSectionMetric 篩選為僅限目標套件，預設為開啟 (Ia219b、b/292208786)

修正錯誤

• 將 fullTracing.enable 檢測引數重新命名為 perfettoSdkTracing.enable，以便與構件名稱和其他參照保持一致。fullTracing.enable 會繼續做為備用方式。(I7cc00)。
• 基準測試程式庫內部追蹤點 (包括微基準測試迴圈/階段追蹤) 現在會顯示在 Studio 系統追蹤檢視器中，並在 Perfetto 中巢狀於正確的程序下。(I6b2e7、b/293510459)。
• 在 API 31 以上版本中移除 macrobenchmark NOT-PROFILEABLE 錯誤，並在已取得 root 權限的 eng/userdebug 裝置上略過可剖析的檢查。(I2abac、b/291722507)。
• 使用 Dex 版面配置最佳化功能時，啟動設定檔規則現在也視為基準設定檔規則。(aosp/2684246、b/293889189)。

1.2.0-beta02 版

2023 年 7 月 26 日

發布 androidx.benchmark:benchmark-*:1.2.0-beta02。1.2.0-beta02 版包含此連結所列的修訂項目。

API 變更

• 新增實驗性 API，可用於微基準測試自訂指標和設定 (例如分析器和追蹤)。(I86101、b/291820856)。

修正錯誤

• 當 OS 的追蹤設定錯誤時，在 macrobench 中回報錯誤 (最近已在 API 26/28 ARM64 模擬器中修正)。(I0a328、b/282191686)。
• 我們已在編譯重設失敗訊息中加入詳細資訊，建議您更新模擬器，因為部分模擬器最近已修正這個問題。(I8c815、b/282191686)。
• 將 androidx.test.uiautomator:uiautomator:2.2.0 設為 api，而非 implementation 依附元件。(I1981e)。

1.2.0-beta01 版本

2023 年 7 月 18 日

發布 androidx.benchmark:benchmark-*:1.2.0-beta01。1.2.0-beta01 版本包含以下修訂項目。

修正錯誤

• 修正 Studio 中基準輸出內容有時會抑制警告的問題，以及解決基準輸出內容前導空白未顯示在 Studio 中的解決方法 (Ia61d0、b/227205461、b/286306579、b/285912360)
• 已修正 FrameTimingMetric 的註解。子指標的名稱為 frameDurationCpuMs。(Ib097f、b/288830934)。

1.2.0-alpha16 版本

2023 年 6 月 21 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha16。1.2.0-alpha16 版包含以下修訂項目。

API 變更

• BaselineProfileRule.collectBaselineProfile() API 已重新命名為 BaselineProfileRule.collect()。(I4b665)

修正錯誤

• androidx.benchmark.profiling.mode = MethodTracing 的 Macrobenchmark 支援功能。(I7ad37、b/285912360)。
• 微基準測試剖析已移至獨立階段，因此會在測量 後依序發生，而非取代測量。系統現在也會將 MethodTracing 追蹤記錄區段納入擷取的 Perfetto 追蹤記錄 (如有)。(I9f657、b/285014599)。
• 使用 Mode.Sum 將計數評估新增至 TraceSectionMetric。(Ic121a、b/264398606)。

1.2.0-alpha15 版

2023 年 6 月 7 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha15。1.2.0-alpha15 版本包含以下修訂項目。

新功能

• 新增實驗性 MemoryUsageMetric，用於追蹤目標應用程式的記憶體用量。(I56453、b/133147125、b/281749311)。
• 新增對 PerfettoTrace.record 的完全自訂 Perfetto 設定支援 (If9d75、b/280460183)
• 新增屬性，可略過基準設定檔產生作業。用法：./gradlew assemble -Pandroidx.baselineprofile.skipgeneration。(I37fda、b/283447020)。

API 變更

• collectBaselineProfile API 一律會產生穩定的基準設定檔。collectStableBaselineProfile API 已遭移除，請改用 collectBaselineProfile。(I17262、b/281078707)
• 將 BaselineProfileRule 的 filterPredicate 引數變更為非空值，並提供等同的預設值，以便在文件中更清楚說明預設篩選器行為。(I3816e)。

修正錯誤

• 請在 dryRunMode 中停用 IsolationActivity 和 Perfetto 追蹤功能，大幅提升效能，因為這些是大部分執行階段的功能。(Ie4f7d)
• 支援使用檢測工具測試引數 androidx.benchmark.profiling.mode=StackSampling 和 androidx.benchmark.profiling.sampleFrequency，在 Macrobenchmark 中進行呼叫堆疊取樣。(I1d13b、b/282188489)。
• 修正在 Android U (API 34) 和模擬器上放置著色器時發生的異常終止問題。(I031ca、b/274314544)。

1.2.0-alpha14 版本

2023 年 5 月 3 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha14。1.2.0-alpha14 版包含以下修訂項目。

修正錯誤

• 修正 FrameTimingMetric 忽略含有不一致影格 ID 的影格。這會導致在近期平台版本 (API 31 以上) 上，某些動畫在 RenderThread 執行動畫時 (例如在漣漪期間) 忽略許多影格。(I747d2、b/279088460)。
• 修正追蹤處理器剖析功能，以便處理超過 64 MB 的追蹤記錄。(Ief831、b/269949822)。
• 修正 Android U 上基準設定檔產生作業失敗的問題，因為 pm dump-profiles 指令的輸出結果不同。(Id1392、b/277645214)。
• 修正 GPU 時鐘鎖定指令碼，以便正確比較字串 (I53e54、b/213935715)

1.2.0-alpha13 版本

2023 年 4 月 5 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha13。1.2.0-alpha13 版本包含以下修訂項目。

API 變更

• 產生基準設定檔時新增設定檔類型參數，以支援即將推出的啟動設定檔功能 (Ie20d7、b/275093123)
• 新增實驗性 TraceMetric API，可根據 Perfetto 追蹤記錄的內容定義完全自訂的指標。(I4ce31、b/219851406)。
• 新增實驗指標，以便判斷基準測試期間的頁面錯誤次數。(I48db0)。

1.2.0-alpha12 版本

2023 年 3 月 22 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha12。1.2.0-alpha12 版本包含以下修訂項目。

新功能

• 新的基準設定檔 Gradle 外掛程式已發布 Alpha 版，可讓您更輕鬆產生基準設定檔，並簡化開發人員的工作流程。

API 變更

• 已移除 API 21 和 22 的 Perfetto 追蹤支援功能，包括 Microbenchmarks 和實驗性 PerfettoTrace API。在這個版本推出之前，UiAutomation 在部分裝置上的連線不穩定。(I78e8c)
• 已為 PerfettoTraceProcessor 新增公開實驗性 API，以便剖析追蹤內容。這是朝著根據 Perfetto 追蹤記錄資料自訂指標的方向邁進的一步。(I2659e、b/219851406)。

1.2.0-alpha11 版本

2023 年 3 月 8 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha11。1.2.0-alpha11 版本包含以下修訂項目。

修正錯誤

• 修正在含有多個 APK 的應用程式套件中，重新安裝或擷取設定檔時，MacrobenchmarkRule 和 BaselineProfileRule 發生異常終止的問題。(I0d8c8、b/270587281)。

1.2.0-alpha10 版本

2023 年 2 月 22 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha10。1.2.0-alpha10 版本包含以下修訂項目。

新功能

• 在 Android 14 以上版本中，Macrobenchmark 不再重新安裝目標應用程式來重設編譯狀態，這要歸功於新的平台功能。先前必須使用已解鎖的裝置，或是在每次基準測試執行前移除所有應用程式狀態 (例如使用者登入)。(I9b08c、b/249143766)。

修正錯誤

• 修正 DryRunMode，讓其不會因編譯略過而與空白設定檔一同當機。而是執行單一疊代並擷取設定檔，確保擷取到某些內容。(I2f05d、b/266403227)。
• 修正在舊版 API 級別中檢查是否有電源狀態時，PowerMetric 異常終止的問題。(5faaf9、b/268253898)。

1.2.0-alpha09 版本

2023 年 1 月 11 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha09。查看 1.2.0-alpha09 版的修訂項。

修正錯誤

• 允許將 None 傳遞至 androidx.benchmark.enabledRules 檢測引數，停用所有基準/基準設定檔產生作業 (I3d7fd、b/258671856)
• 修正應用程式模組中的 PerfettoTrace 擷取 (亦即非自我檢測測試 APK) (I12cfc)
• 修正 Studio 輸出內容中的基準設定檔 ADB 提取引數順序 (I958d1、b/261781624)
• 現在嘗試執行 Macrobenchmark 時，系統可正確辨識 Arm 模擬器 API 33，後者也能正確顯示警告 (69133b、b/262209591)
• 在 Macrobenchmark 中略過無電池裝置的電池電量檢查 (fe4114、b/232448937)

1.2.0-alpha08 版本

2022 年 12 月 7 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha08。查看 1.2.0-alpha08 版的修訂項。

API 變更

• 已新增實驗性的新 API PerfettoTrace.record {} 和 PerfettoTraceRule，以擷取 Perfetto 追蹤記錄 (也稱為系統追蹤) 作為測試的一部分，以檢查測試的行為和效能。(I3ba16)
• BaselineProfileRule 現在可接受篩選器述詞，而不是套件前置字串清單。這樣一來，測試就能完全控制篩選功能。(I93240)
• 新增實驗性 API BaselineProfileRule.collectStableBaselineProfile，等待 N 個疊代的基準設定檔保持穩定。(I923f3)
• 新增使用 BaselineProfileRule 產生基準設定檔時，指定輸出檔案名稱前置字串的功能。(I7b59f, b/260318655)

修正錯誤

• 改善檔案輸出寫入的安全性，避免系統無法靜默輸出 / 附加輸出檔案，尤其是在 API 21/22 上。(If8c44, b/227510293)
• 修正 simpleperf 追蹤記錄輸出，以正確建立和放置檔案。這通常也能解決無法用 Gradle 提取檔案的問題。(I12a1c, b/259424099)
• 改善因為 profileinstaller 過舊而出現的列印錯誤問題。現在系統會指出需要更新 profileinstaller 版本 (1.2.1)，才能測量 API 31 到 33 的基準設定檔，不再只是表示不支援目前版本。(Ia517f, b/253519888)
• 修正數個殼層指令失敗的錯誤訊息 列印需要 API <=23，包括perfetto無法擷取二進位檔設定，以及追蹤記錄失敗 (Ib6b87、b/258863685)
• 自動將產生的設定檔規則排序，盡量減少隨時間變化 (在檢查機制規則至來源控制時) 的變更次數。(Ie2509)
• 已修正 Android 13 (API 33) 之下未取得 Root 權限的版本當機訊息 (Expected no stderr from echo 3 > /proc/sys/vm/drop_caches)。(I6c245、b/259508183)

已知問題-MacrobenchmarkScope.dropShaderCache() profileinstaller 資訊清單中缺少播送註冊資料庫，因此可能當機。(I5c728、b/258619948) 如要解決 profileinstaller:1.3.0-alpha02 中的問題，請將以下內容新增到應用程式的 (而非基準) AndroidManifest.xml 中：

  <!-- workaround bug in profileinstaller 1.3.0-alpha02, remove when updating to alpha03+ -->
  <receiver
    android:name="androidx.profileinstaller.ProfileInstallReceiver"
    android:permission="android.permission.DUMP"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.profileinstaller.action.BENCHMARK_OPERATION" />
    </intent-filter>
  </receiver>

1.2.0-alpha07 版

2022 年 11 月 9 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha07。查看 1.2.0-alpha07 版的修訂項。

API 變更

• 新增 PowerMetric API，用於測量 Macrobenchmark 中的能量和電力 (Ife601、b/220183779)
• 已修正 MacrobenchmarkScope.dropShaderCache()，以便確實捨棄著色器快取。這麼做會從 StartupMode.COLD 基準移除約 20 毫秒的雜訊，因為現在每次疊代都會清除著色器。先前，使用暖身疊代的 Partial 編譯作業會回報不正確的數字，因為著色器快取較有可能在暖身時發生。這項修正需要使用已解鎖裝置，或是在目標應用程式中使用 profileinstaller:1.3.0-alpha02。如要瞭解 ProfileInstaller 程式庫的 API 變更，請參閱 ProfileInstaller 1.30-alpha02 頁面。(Ia5171、b/231455742)
• 新增了 TraceSectionMode("label", Mode.Sum)，可讓您針對標有相同標籤的多個追蹤記錄部分評估總使用時間。舉例來說，TraceSectionMetric("inflate", Mode.Sum) 會就 Macrobenchmark 中花在加載上的總時間回報指標 inflateMs。此外，我們也移除了 API 29 相關規定，因為 TraceSectionMetric 與 androidx.tracing.Trace 並用時可以回到較低的 API 級別，也就是在目標應用程式中使用 forceEnableAppTracing。(Id7b68、b/231455742)

修正錯誤

• 驗證所有輸出內容/錯誤，藉此提升所有內部殼層指令的安全性。(I5984d、b/255402908、b/253094958)
• 在基準設定檔 adb pull 指令中指定裝置，這樣在連接多個裝置 (最多一個模擬器) 時，便可輕鬆複製提取指令 (I6ac6c、b/223359380)
• 如果 Macrobenchmark 測試 APK 未設為自行檢測，即會導致錯誤。這項錯誤會禁止系統從目標應用程式處理程序中執行巨集基準化作業。在處理過程中，Macrobench 將無法編譯/終止/冷啟動應用程式，也無法控制自身權限 (I4279b)
• 修正 measureRepeated() 中的一個問題，此問題會導致 StartupMode.COLD 不會在 setupBlock 後終止目標處理程序。現在與應用程式互動的 setupBlock 不會讓應用程式處理程序持續執行，冷啟動測量也會失效。(I8ebb7)

1.2.0-alpha06 版本

2022 年 10 月 24 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha06。查看 1.2.0-alpha06 版的修訂項目。

API 變更

• BaselineProfileRule 在 Android 13 (API 33) 上不再需要根層級，而且不再處於實驗階段 (Ie0a7d、b/250083467、b/253094958)
  • 此變更還修正了在未取得 Root 權限的裝置上，設定檔從應用程式清除至磁碟的方式，但必須更新目標應用程式的 profileinstaller 依附元件。
  • 如要在未取得 Root 權限的裝置上使用 BaselineProfileRule 或 CompilationMode.Partial(warmupIterations)，您還必須更新目標應用程式以便使用 androidx.profileinstaller.profileinstaller:1.3.0-alpha01。這能使設定檔正確地清除至磁碟，以便進行編譯/擷取。

修正錯誤

• 修正 API 33 以上版本的 SampledProfiling 當機問題。(I40743、b/236109374)

1.2.0-alpha05 版本

2022 年 10 月 5 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha05。查看 1.2.0-alpha05 版的修訂項。

修正錯誤

• 修正 Studio 系統追蹤記錄檢視器中頁框細目的基準擷取追蹤記錄問題 (I3f3ae、b/239677443)
• 修正 FrameTimingMetric 以將 FrameOverrun 列為需要 API 31 而非 29 (I716dd、b/220702554)
• 在 BaselineProfileRule 中設定疊代，如果未安裝目標套件，則明確擲回 (已在 MacrobenchmarkRule 中實現)。(Ic09a3, b/227991471)

1.2.0-alpha04 版本

2022 年 9 月 21 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha04。1.2.0-alpha04 版包含此連結所列的修訂項目。

新功能

• 將 dryRunMode.enable 檢測引數支援新增至 Macrobenchmark (已推出微型版本) 加快本機開發作業，以及驗證應用程式自動化功能 (例如在預先提交中)。這會將疊代次數覆寫為 1、略過編譯、封鎖所有設定錯誤，以及停用評估 .json 檔案輸出功能。(Ib51b4、b/175149857)

  使用 Gradle 指令列：

  ./gradlew macrobenchmark:cC -P android.testInstrumentationRunnerArguments.androidx.benchmark.dryRunMode.enable=true
  

  在 build.gradle 中:

  android {
      defaultConfig {
          testInstrumentationRunnerArgument 'androidx.benchmark.dryRunMode.enable', 'true'
      }
  }
  

修正錯誤

• 已修正 StartupTimingMetric，不再需要透過 MacrobenchmarkScope.startActivityAndWait() 啟動測量的活動。這表示指標可擷取通知、Context.startActivity()、應用程式內活動型導覽或殼層指令等的啟動項目。(Ia2de6、b/245414235)
• 修正錯誤，其中 startActivityAndWait 嘗試透過降低影格偵測嚴格程度，以在模擬器上等待啟動時，會出現逾時。(Ibe2c6、b/244594339、b/228946895)

1.2.0-alpha03 版本

2022 年 9 月 7 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha03。查看 1.2.0-alpha03 版的修訂項。

新功能

• 新增了用於獨立使用 BenchmarkState 的實驗性 API，與 BenchmarkRule / JUnit4 分開使用。(Id478f、b/228489614)。

修正錯誤

• 已為 startActivityAndWait 新增 Leanback 備用廣告。(01ed77, b/242899915)

1.2.0-alpha02 版本

2022 年 8 月 24 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha02。1.2.0-alpha02 版包含此連結所列的修訂項目。

API 變更

• 即使已啟用 Root 權限，MacrobenchmarkScope.killProcess() 的預設值仍為 am force stop，但在基準設定檔產生期間除外。您可以使用選擇性的布林值引數覆寫這個值。(02cce9、b/241214097)

修正錯誤

• 支援為系統應用程式產生基準設定檔。(I900b8、b/241214097)
• 支援在未啟用 Root 權限的裝置上檢查 ODPM 電源指標。(a38c78、b/229623230)

1.2.0-alpha01 版本

2022 年 7 月 27 日

發布 androidx.benchmark:benchmark-*:1.2.0-alpha01。1.2.0-alpha01 版包含此連結所列的修訂項目。

新功能

• 新的 tracing-perfetto-common 元件，可讓工具在其公開的應用程式中啟用 Perfetto SDK 追蹤功能 (I2cc7f)

• 新增了 androidx.benchmark.enabledRules 檢測引數，以使巨集基準篩選功能僅篩選基準或基準設定檔產生器。傳入「Macrobenchmark」或「BaselineProfile」，讓系統僅執行一種類型的測試，例如在模擬器中僅產生 BaselineProfiles 時。支援以半形逗號分隔的清單。(I756b7、b/230371561)

  例如，在 Macrobenchmark 的 build.gradle 中：

  android {
      defaultConfig {
          testInstrumentationRunnerArgument 'androidx.benchmark.enabledRules', 'BaselineProfile'
      }
  }
  

  或是來自 Gradle 指令列：

  ./gradlew macrobenchmark:cC -P android.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile
  

API 變更

• 新增 PowerMetric，用於測量基準中的能量和電力工作 (I9f39b, b/220183779)
• 新增編譯模式 CompilationMode.Ignore，可略過設定檔的重設和編譯。(Ibbcf8, b/230453509)
• 在 BaselineProfileRule#collectBaselineProfile 中新增參數，以依套件名稱篩選輸出檔案 (If7338、b/220146561)
• 可讓開發人員放電裝置以測量耗電量。(I6a6cb)
• 新增了清除 MacrobenchmarkScope 中的著色器快取的功能。(I32122)
• 可讓開發人員設定指標類型的顯示方式，以及所需的子系統類別的詳細資料。(I810c9)
• 先前，如果在不支援的裝置上執行，系統會將 UnsupportedOperationException 擲回基準。現在，只有在不支援的裝置上 (例如 PowerMetric.configure) 使用指標時，系統才會產生 UOE。(I5cf20、b/227229375)
• 新增了 TotalPowerMetric 和 TotalEnergyMetric，用於評估 Macrobenchmark 中每個系統類別的總功率和能量。(I3b26b, b/224557371)

修正錯誤

• 修正應用程式編譯在未取得 Root 權限的 Macrobenchmark 版本之間未正確重設的問題。很抱歉，每次疊代時都必須重新安裝 APK，此舉將會清除每個 Macrobenchmark 的應用程式資料。(I31c74、b/230665435)
• 修正 API 21/22 上的追蹤記錄異常終止問題 (If7f6、(b/227509388)、(b/227510293)、(b/227512788))
• 全面改造用來偵測「活動完成推出」的機制，修正 MacroBenchmark 啟動程序中「無法讀取任何指標」的例外情況。(Ia517c)

1.1.1 版本

1.1.1 版本

2022 年 11 月 9 日

發布 androidx.benchmark:benchmark-*:1.1.1。1.1.1 版包含此連結所列的修訂項目。

修正錯誤

• 修正部分 Android11 (API 30) 以上版本裝置會發生的 android.system.ErrnoException: open failed: EACCES 問題。這是從 1.2.0-alpha01 中挑選出來的修正程序。(aosp/2072249)

1.1.0 版本

1.1.0 版本

2022 年 6 月 15 日

發布 androidx.benchmark:benchmark-*:1.1.0。查看 1.1.0 版的修訂項。

• 這個版本與 androidx.benchmark:benchmark-*:1.1.0-rc03 相同。

自 1.0.0 版本以來的重要異動

• 支援 Jetpack Macrobenchmarks，讓您可以評估整個應用程式的互動情形，例如「啟動」和「捲動」，並能提供擷取追蹤記錄及測量追蹤記錄區段的功能。

• 支援基準設定檔

  • CompilationMode.Partial 可測量基準設定檔的成效。
  • @BaselineProfileRule 可自動針對指定的關鍵使用者旅程產生基準設定檔。

• 支援在執行 Microbenchmark 中的配置指標及剖析。

1.1.0-rc03 版本

2022 年 6 月 1 日

發布 androidx.benchmark:benchmark-*:1.1.0-rc03。1.1.0-rc03 版包含此連結所列的修訂項目。

修正錯誤

• 避免為每個基準疊代重新安裝目標套件。( aosp/​​2093027，b/231976084)

• 從 pressHome() 移除 300ms 延遲。(aosp/2086030，b/231322975)

• 最佳化處理系統背後的殼層指令，改善 Macrobenchmark 疊代速度。(aosp/2086023，b/231323582)

• 使用 Macrobenchmark 產生基準設定檔時，支援 Gradle 管理的裝置。(aosp/2062228，b/228926421)

1.1.0-rc02 版本

2022 年 5 月 11 日

發布 androidx.benchmark:benchmark-*:1.1.0-rc02。查看 1.1.0-rc02 版的修訂項。

• 請注意，這個版本包含行為變更，因為系統現已全面重新安裝各基準的應用程式，以確保測量結果正確無誤。

修正錯誤/行為變更

• 修正了應用程式編譯在 Macrobenchmark 之間未正確重設，且在未取得 Root 權限的版本上完全無法重設的問題。這修正了在多個情況下，執行多個測試會導致 CompilationMode 對測量幾乎沒有影響的問題。為解決此問題，目標應用程式現已徹底重新安裝各個測試方法，這將會清除每個 Macrobenchmark 之間的應用程式資料。(I31c74、b/230665435)

• 由於這樣可防止應用程式在測試之前先設定狀態，現在可略過編譯/重新安裝解決此問題。舉例來說，您可以使用殼層指令 cmd package compile -f -m speed <package> 完整編譯目標，然後略過 Macrobenchmark 的編譯步驟。

  例如，在 Macrobenchmark 的 build.gradle 中：

  android {
      defaultConfig {
          testInstrumentationRunnerArgument 'androidx.benchmark.compilation.enabled, 'false'
      }
  }
  

  或是來自 Gradle 指令列：

  ./gradlew macrobenchmark:cC -P android.testInstrumentationRunnerArguments.androidx.benchmark.compilation.enabled=false
  

• 透過加入 androidx.benchmark.enabledRules 檢測引數，您可以輕鬆在 Macrobenchmark 和基準設定檔產生的測試之間共用模組。傳入「Macrobenchmark」或「BaselineProfile」，讓系統僅執行一種類型的測試，例如在模擬器中產生 BaselineProfiles 時。(I756b7、b/230371561)

  例如，在 Macrobenchmark 的 build.gradle 中：

  android {
      defaultConfig {
          testInstrumentationRunnerArgument 'androidx.benchmark.enabledRules', 'BaselineProfile'
      }
  }
  

  或是來自 Gradle 指令列：

  ./gradlew macrobenchmark:cC -P android.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile
  

1.1.0-rc01 版本

2022 年 4 月 20 日

發布 androidx.benchmark:benchmark-*:1.1.0-rc01。查看 1.1.0-rc01 版的修訂項。

修正錯誤

• Android Studio 中的基準設定檔輸出連結現在使用不重複的檔案名稱。這樣一來，輸出內容就會一律反映出使用 BaselineProfileRule 的最新結果。(aosp/2057008、b/228203086)

1.1.0-beta06 版本

2022 年 4 月 6 日

發布 androidx.benchmark:benchmark-*:1.1.0-beta06。查看 1.1.0-beta06 版的修訂項。

修正錯誤

• 修正 API 21/22 的追蹤記錄異常終止問題 (If7fd6、b/227509388)
• 全面改造用來偵測「活動完成推出」的機制，修正 MacroBenchmark 啟動程序中「無法讀取任何指標」的例外情況。(Ia517c)
• 修正使用 CompilationMode.None() 時 Macrobenchmark 的啟動指標。實施這項變更前，CompilationMode.Partial() 似乎比 Compilation.None() 慢。(611ac9)。

1.1.0-beta05 版本

2022 年 3 月 23 日

發布 androidx.benchmark:benchmark-*:1.1.0-beta05。查看 1.1.0-beta05 版的修訂項。

修正錯誤

• 使用 CompilationMode.None 時，在略過設定檔安裝作業後終止套件。(aosp/1991373)
• 修正問題：使用 StartupMode.COLD 時，Macrobenchmark 無法收集啟動指標。(aosp/2012227、b/218668335)

1.1.0-beta04 版本

2022 年 2 月 23 日

發布 androidx.benchmark:benchmark-*:1.1.0-beta04。查看 1.1.0-beta04 版的修訂項。

修正錯誤

• 修正 Android 10 中遺漏的指標，以及在追蹤記錄中未正確擷取程序名稱而引發的 NoSuchElementException。(Ib4c17、b/218668335)

• 使用 PowerManager 在 Q (API 29) 以上版本進行過熱保護偵測作業。這會大幅降低過熱保護偵測機制 (經過 90 秒等待期後重新檢測) 的誤報頻率，並且加快使用者建構作業的速度。此外，如果就所處環境而言，裝置鎖定的溫度太高，導致時脈頻率呈現鎖定狀態時，上述作法還可以讓系統持續提供過熱保護偵測功能。(I9c027、b/217497678、b/131755853)。

• 篩選 Simpleperf 取樣剖析，將結果限定在僅限 measureRepeated 執行緒，進而簡化檢查作業 (Ic3e12、b/217501939)

• 支援多程序應用程式中的已命名 UI 子程序指標 (Ice6c0、b/215988434)

• 篩選基準設定檔規則，以便只針對 Android 9 (SDK 28)。aosp/1980331 b/216508418

• 在使用 Compilation.None() 時略過設定檔安裝程序。此外，當應用程式使用舊版 androidx.profileinstaller 和 Android Gradle 外掛程式時，系統也會回報警告。aosp/1977029

1.1.0-beta03 版本

2022 年 2 月 9 日

發布 androidx.benchmark:benchmark-*:1.1.0-beta03。1.1.0-beta03 版包含此連結所列的修訂項目。

API 變更

• 將 AudioUnderrunMetric 新增至 Macrobenchmark 程式庫，並伴隨實驗性標記，以利系統偵測音訊不足的現象 (Ib5972)

• BaselineProfileRule 不再接受 setup 區塊，因為其功能與 profileBlock 相同。(Ic7dfe、b/215536447)。

  例如

  @Test
  fun collectBaselineProfile() {
      baselineRule.collectBaselineProfile(
          packageName = PACKAGE_NAME,
          setupBlock = {
              startActivityAndWait()
          },
          profileBlock = {
              // ...
          }
      )
  }
  

  @Test
  fun collectBaselineProfile() {
      baselineRule.collectBaselineProfile(
          packageName = PACKAGE_NAME,
          profileBlock = {
              startActivityAndWait()
              // ...
          }
      )
  }
  

修正錯誤

• 修正問題：當連結至 Studio 輸出時，microbench 分析器追蹤記錄在後續的執行作業中就無法更新 (I5ae4d、b/214917025)
• 禁止 API 23 編譯編譯指令 (Ice380)
• 已重新命名 FrameCpuTime -> FrameDurationCpu、FrameUiTime -> FrameDurationUi 以說明這些是時間長度而非時間戳記，以及比對前置字串。(I0eba3、b/216337830)。

1.1.0-beta02 版本

2022 年 1 月 26 日

發布 androidx.benchmark:benchmark-*:1.1.0-beta02。查看 1.1.0-beta02 版的修訂項。

修正錯誤

• Microbenchmark 堆疊取樣/方法追蹤記錄設定檔結果現已連結至 Studio 輸出內容，與其他剖析結果類似，且不隱藏分配指標。(Idcb65、b/214440748、b/214253245)。
• BaselineProfileRule 現可在 logcat 和 Studio 輸出中列印 adb pull 指令，以擷取產生的 BaseProfile 文字檔案。(f08811)

1.1.0-beta01 版本

2022 年 1 月 12 日

發布 androidx.benchmark:benchmark-*:1.1.0-beta01。查看 1.1.0-beta01 版的修訂項。

修正錯誤

• 修正忽略分析器引數啟用的問題。(I37373、b/210619998)。
• 已移除已淘汰的 CompliationModes (I98186、b/213467659)
• 已將 CompilationMode.Partial 的基準設定檔引數切換為列舉以清楚呈現。(Id67ea)

1.1.0-alpha13 版本

2021 年 12 月 15 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha13。查看 1.1.0-alpha13 版的修訂項。

API 變更

• 針對 Android Q (API 29 以上版本) 將低負載系統追蹤加入 microbench 輸出內容。請注意，這項操作目前不會透過 android.os.Trace 或 androidx.tracing Jetpack API 擷取自訂追蹤記錄，以免影響結果。這項追蹤記錄應有助於診斷不穩定性，特別是基準以外的來源。(I298be、b/205636583、b/145598917)。
• 將 CompilationModes 界定為三個類別：「完整」、「無」、「部分」。先前則是以編譯引數 (現在視為導入詳細資料) 和功能的名稱命名，而不一致。這能讓您更清楚地瞭解各平台版本優缺點、潛在組合和行為。(I3d7bf、b/207132597)
• 系統目前一律會依據設定組合及測量，您現在可以查詢套件名稱和疊代 (某些準備情境中疊代可能為 null)。(Id3b68、b/208357448、b/208369635)。

修正錯誤

• 修正了 CompilationMode.Speed 錯誤視為 None (I01137)

1.1.0-alpha12 版本

2021 年 11 月 17 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha12。查看 1.1.0-alpha12 版的修訂項。

新功能

• 新增自訂的 TraceSectionMetric 以提供自訂追蹤記錄的測量數據。(I99db1、b/204572664)

修正錯誤

• 每次疊代時喚醒裝置，以確保能夠測試 UI；必須停用螢幕鎖定功能。(Ibfa28、b/180963442)。
• 修正在 StackSampling 剖析模式與非 Root 權限裝置上的多重當機問題 (Icdbda、b/202719335)
• 在每個疊代的結束時移除 0.5 秒的睡眠。如果發現變更缺少遺漏的指標，請提交錯誤。(Iff6aa)
• 降低資料遺失的風險，並減少追蹤資料的記憶體負擔 (Id2544、b/199324831、b/204448861)
• 改用精簡的壓縮儲存空間格式，減少約 40% 的追蹤記錄大小。(Id5fb6、b/199324831)。
• 更新啟動指標的實作，一律在轉譯執行緒結束時一律結束。這樣會跨平台版本更加穩定，並且能夠更精準地對應應用程式內評估項目。(Ic6b55)

1.1.0-alpha11 版本

2021 年 11 月 3 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha11。1.1.0-alpha11 版包含此連結所列的修訂項目。

API 變更

• 現在 Macrobenchmark 的 minSdkVersion 為 23 (If2655)
• 新增 BaselineProfileRule 的實驗性功能，可針對應用程式的重要使用者歷程產生基準設定檔。詳細的說明文件。(Ibbefa、b/203692160)
• 移除為 Java 呼叫端新增的 measureRepeated 介面變化版本，因為這樣會導致完成/解決方法造成混淆。Java 呼叫者將再次需要從 measureRepeated 傳回 Unit 例項。如果造成不便，請回報錯誤，我們會在日後的版本中重新審視這個問題。(Ifb23e、b/204331495)

1.1.0-alpha10 版本

2021 年 10 月 27 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha10。查看 1.1.0-alpha10 版的修訂項。

API 變更

• Backport StartupTimingMetric 返回 API 23。這個新導入方式還能進一步處理 reportFullyDrawn() 來處理等待的內容轉譯完成。(If3ac9、b/183129298)
• 將 Java 呼叫新增至多個 MacrobenchmarkScope 方法的 JvmOverloads 方法。(I644fe、b/184546459)。
• 提供替代的 MacrobenchmarkRule.measureRepeated 函式，使用 Consumer<MacrobenchmarkScope> 進行 Java 語言的慣用用途。(If74ab、b/184546459)

修正錯誤

• 修正未儘早開始，且缺少指標資料追蹤記錄。預期應修正程式庫本身造成的「在基準期間無法讀取任何指標」的例外狀況。(I6dfcb、b/193827052、b/200302931)。
• FrameBalanceSlack 已重新命名為 FrameOverrun，以便釐清其含意，也就是影格時間超出限制。(I6c2aa、b/203008701)

1.1.0-alpha09 版本

2021 年 10 月 13 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha09。查看 1.1.0-alpha09 版的修訂項。

修正錯誤

• 支援在 API 31/S+ 的情況下，不使用 Root 權限來捨棄核心頁面快取，這樣可增加 StartupMode.COLD 啟動內容的準確度。(Iecfdb、b/200160030)

1.1.0-alpha08 版本

2021 年 9 月 29 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha08。查看 1.1.0-alpha08 版的修訂項。

API 變更

• 啟用捲動 Macrobenchmark 以返回 API 23 (If39c2、b/183129298)
• 在 UI 和 JSON 輸出中新增取樣指標類型，著重於各個疊代的多個樣本百分位數。(I56247、b/199940612)。
• 切換為整個基準資料庫的浮點指標 (在 Studio UI 中截斷)。(I69249、b/197008210)。

1.1.0-alpha07 版本

2021 年 9 月 1 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha07。查看 1.1.0-alpha07 版的修訂項。

API 變更

• 將最低 API 提高至 21，反映未來支援的 API 級別下限。目前支援的最低 API 持續透過 RequiredApi() 傳達，且目前為 29 (I440d6、b/183129298)

修正錯誤

• 修正 ProfileInstaller，讓使用基準設定檔的應用程式更容易使用 CompilationMode.BaselineProfile 執行 MacroBenchmarks。(I42657、b/196074999) 注意：必須一併更新為 androidx.profileinstaller:profileinstaller:1.1.0-alpha04 以上。
• StartupMode.COLD + CompilationMode.None 的基準功能較穩定。(I770cd、b/196074999)

1.1.0-alpha06 版本

2021 年 8 月 18 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha06。查看 1.1.0-alpha06 版的修訂項。

API 變更

• 新增了 androidx.benchmark.iterations 檢測引數，以在本機測試/剖析時手動覆寫疊代計數 (6188be、b/194137879)

修正錯誤

• 改用 Simpleperf 做為 API 29 以上版本中的預設取樣分析器 (Ic4b34、b/158303822)。

已知問題

• CompilationMode.BaselineProfile 仍在開發階段。目前請避免透過該項目判斷設定檔的品質。

1.1.0-alpha05 版本

2021 年 8 月 4 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha05。查看 1.1.0-alpha05 版的修訂項。

1.1.0-alpha04 在發布前已取消，原因為偶發性的當機情形。b/193827052

API 變更

• 將 startActivityAndWait 切換為透過 am start 叫用啟動，以減少每個評估疊代的時間 (約 5 秒)，且不再支援意圖 Parcelable (I5a6f5、b/192009149)

修正錯誤

• 降低過熱保護偵測機制的敏感度，如果經常偵測到溫度過熱的情況，則必須重新計算基準。(I7327b)
• 修正 FrameTimingMetric 可支援 Android S Beta 版 (Ib60cc、b/193260119)
• 使用 EmptyActivity 即可讓目標應用程式退出強制停止狀態，以提升 CompilationMode.BaselineProfile 的支援程度。(Id7cac、b/192084204)。
• 將追蹤檔案副檔名變更為 .perfetto-trace，以符合平台標準 (I4c236、b/174663039)。
• StartupTimingMetric 會輸出「fullyDrawnMs」指標，以評估應用程式完成算繪所需的時間。如要為您的應用程式定義這項指標，請在初始內容準備就緒時 (例如從 DB 或網路載入初始清單項目) 呼叫 Activity.reportFullyDrawn。(可使用 reportFullyDrawn 方法，而不針對 ComponentActivity 進行建構版本檢查)。請注意，測試時間必須夠長才能擷取指標 (startActivityAndWait 不需等待 reportFullyDrawn) (If1141、b/179176560)
• 將 Ui 中繼資料的追蹤記錄附加至追蹤記錄超過 50 毫秒 (Ic8390、b/193923003)
• 停止追蹤時，輪詢頻率會大幅增加，例如啟動基準執行階段可能減少 30% (Idfbc1、b/193723768)

1.1.0-alpha03 版本

2021 年 6 月 16 日

發布 androidx.benchmark:benchmark-*:1.1.0-alpha03。1.1.0-alpha03 版包含此連結所列的修訂項目。

新功能

• 新增了 CompilationMode.BaselineProfile，以支援使用 Jetpack ProfileInstaller 程式庫安裝的設定檔。(aosp/1720930)

修正錯誤

• 用來略過基準錯誤的範例 Gradle 程式碼已更新為使用非淘汰的 API，其語法同時支援 .gradle.kts 使用者。

  例如

  testInstrumentationRunnerArguments["androidx.benchmark.suppressErrors"] = "EMULATOR,LOW-BATTERY"
  

1.1.0-alpha02 版本

2021 年 5 月 18 日

基準版本 1.1.0-alpha02 為基準化功能提供了重要的元件 - Macrobenchmark。除了可評估 CPU 迴圈的「基準」之外，您還可以運用「Macrobenchmark」評估整個應用程式的互動情形，例如啟動及捲動畫面，以及擷取追蹤記錄。詳情請參閱程式庫說明文件。

發布 androidx.benchmark:benchmark-*:1.1.0-alpha02。查看 1.1.0-alpha02 版的修訂項。

新功能

新增了的 Macrobenchmark 構件 (androidx.benchmark:benchmark-macro-junit4 和 androidx.benchmark:benchmark-macro)

• 從本機或持續整合應用程式擷取啟動、捲動/動畫成效指標
• 從 Android Studio 擷取及檢查追蹤記錄

修正錯誤

• 解決 Android 12 輸出目錄的殼層權限問題 (注意：可能需要將 Android Gradle 外掛程式更新至 7.0.0 初期測試版本，並將 Android Studio 更新為 Arctic Fox (2020.3.1)，才能繼續擷取受影響裝置上的輸出檔案)。(Icb039)
• 支援 BenchmarkPlugin 的配置快取 (6be1c1、b/159804788)
• 簡化檔案輸出 - 預設為在不需要 requestLegacyExternalStorage=true 的目錄中 (8b5a4d、b/172376362)
• 修正程式庫列印 logcat 警告，指出在不存在的平台版本上找不到 JIT 執行緒。(I9cc63、b/161847393)。
• 修正讀取裝置頻率上限的問題。(I55c7a)

1.1.0-alpha01 版本

2020 年 6 月 10 日

發布 androidx.benchmark:benchmark-common:1.1.0-alpha01、androidx.benchmark:benchmark-gradle-plugin:1.1.0-alpha01 和 androidx.benchmark:benchmark-junit4:1.1.0-alpha01。查看 1.1.0-alpha01 版的修訂項。

1.1 的新功能

• 分配指標 - 基準現在會在準備和時間點之後執行額外階段，並擷取分配次數。分配可能會導致舊版平台的效能問題 (在 O 為 140ns，到了 M 則為 8ns；測量裝置為 Nexus5X 且時脈已鎖定)。這項指標會顯示在 Android Studio 主控台輸出結果中，以及
• 剖析支援 - 您現在可以擷取基準執行的剖析資料作業，以檢查程式碼執行速度變慢的原因。基準功能可讓您擷取方法或從 ART 進行方法取樣。您可以在 Android Studio 中依序點選「File」>「Open」，透過分析器檢查這些檔案。
• 基準 Gradle 外掛程式現在提供簡易設定的預設設定：
  • 根據預設將 testBuildType 設為發布版本，避免使用內建程式碼涵蓋率功能的依附元件。這個版本的 buildType 也設為預設的 buildType 類型，讓 Android Studio 在初次開啟專案時，自動選取正確的建構變化版本 (b/138808399)
  • signingConfig.debug 是預設的簽署設定 (b/153583269)

** 修正錯誤 **

• 大幅減少暖機的轉換負擔，也就是每項基準的第一項測量值都比其他基準高。在規模較小的基準 (1 毫秒或更短) 內，這個問題較為明顯。(b/142058671)
• 修正了從指令列執行時，每個基準列印的 InstrumentationResultParser 個錯誤。(I64988、b/154248456)。

已知問題

• 指令列的 Gradle 叫用不會直接列印結果。如要解決這個問題，您可以透過 Studio 執行，或是剖析 JSON 輸出檔案來檢查結果。
• 如果裝置已安裝應用程式的 applicationId 結尾為「android」或「download」(不區分大小寫)，就無法從基準報表功能提取報表。使用者遇到這個問題時，應將 Android Gradle 外掛程式升級至 4.2-alpha01 以上版本。

1.0.0 版本

1.0.0 基準版本

2019 年 11 月 20 日

發布 androidx.benchmark:benchmark-common:1.0.0、androidx.benchmark:benchmark-gradle-plugin:1.0.0 和 androidx.benchmark:benchmark-junit4:1.0.0，1.0.0-rc01 沒有任何變更。查看 1.0.0 版的修訂項。

1.0.0 的主要功能

基準資料庫可讓您編寫應用程式程式碼的效能基準，並快速取得結果。

這項功能可避免建構和執行階段設定問題，並穩定裝置效能，確保測量結果的準確性和一致性。您可以直接在 Android Studio 中執行基準測試，或是在持續整合中測試基準效能，藉此觀察程式碼效能變化，並避免發生迴歸問題。

主要功能包括：

• 時脈穩定功能
• 自動設定對話串的優先順序
• 支援 UI 效能測試，例如 RecyclerView 範例
• JIT 感知準備與循環循環
• 後續處理的 JSON 基準輸出

1.0.0-rc01 版本

2019年10月23日

發布 androidx.benchmark:benchmark-common:1.0.0-rc01、androidx.benchmark:benchmark-gradle-plugin:1.0.0-rc01 和 androidx.benchmark:benchmark-junit4:1.0.0-rc01。查看 1.0.0-rc01 版的修訂項。

新功能

• 已將基準系統追蹤記錄新增至基準

修正錯誤

• 已修正指標穩定性不穩定的問題，導致 JIT 在排除問題之前而無法完成 (b/140773023)
• Android Gradle 外掛程式 3.5 和 3.6 統合版的 JSON 輸出目錄

1.0.0-beta01 版本

2019 年 10 月 9 日

發布 androidx.benchmark:benchmark-common:1.0.0-beta01、androidx.benchmark:benchmark-gradle-plugin:1.0.0-beta01 和 androidx.benchmark:benchmark-junit4:1.0.0-beta01。查看 1.0.0-beta01 版的修訂項。

新功能

• 在每次準備之前執行垃圾收集作業，將記憶體壓力從一個基準降到下一個基底 (b/140895105)

修正錯誤

• 新增 androidx.annotation:android-experimental-lint 依附元件，讓 Java 程式碼在未使用實驗性 API 時能正確產生 Lint 錯誤，類似 Kotlin 呼叫端的 Kotlin 實驗性註解所提供的程式碼。
• 現在可正確偵測 Android Gradle 外掛程式 3.6 中輸出的 additionalTestOutputDir 檢測引數，以確認 AGP 何時會處理資料複製作業。
• 修正 JSON 中未偵測到的時鐘頻率，以正確列印 -1 (b/141945670)。

1.0.0-alpha06 版本

2019 年 9 月 18 日

發布 androidx.benchmark:benchmark-common:1.0.0-alpha06、androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha06 和 androidx.benchmark:benchmark-junit4:1.0.0-alpha06。查看 1.0.0-alpha06 版的修訂項。

新功能

• 新增了檢查工具測試中未正確使用的舊套件檢查功能，但這篇文章提供更實用的錯誤訊息

API 變更

• 實驗性註解 ExperimentalAnnotationReport 現已公開。是否能使用實驗性 BenchmarkState#report API

1.0.0-alpha05 版本

2019 年 9 月 5 日

發布 androidx.benchmark:benchmark-common:1.0.0-alpha05、androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha05 和 androidx.benchmark:benchmark-junit4:1.0.0-alpha05。您可以前往這裡查看這個版本包含的修訂項目。

API 變更

• BenchmarkState.reportData API 現已標示為實驗性質

修正錯誤

• 修正問題：時鐘鎖定功能在缺少 cut 或 expr 殼層公用程式的裝置上無法運作。
• 以往有 ./gradlew lockClocks 工作會啟動舊版 su 公用程式，且該版本不支援 -c 旗標，這個問題現已修正。

1.0.0-alpha04 版本

2019 年 8 月 7 日

發布 androidx.benchmark:benchmark-common:1.0.0-alpha04、androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha04 和 androidx.benchmark:benchmark-junit4:1.0.0-alpha04。您可以前往這裡查看這個版本包含的修訂項目。

我們還新增了一個說明文件，說明如何在沒有 Gradle 的情況下使用基準資料庫，以便搭配不同的建構系統 (例如 Bazel 或 Buck) 使用，並在持續整合 (CI) 環境中執行。詳情請參閱「在不使用 Gradle 的情況下建立基準」和「在持續整合中執行基準」。

新功能

• Gradle 外掛程式
  • 現在會自動停用測試涵蓋範圍，並預設使用 AndroidBenchmarkRunner (b/138374050)
  • 支援新的 AGP 式資料複製功能，執行基準和使用 AGP 3.6 以上版本時即可提供這項功能
• JSON 格式新增項目
  • 輸出總基準測試執行時間 (b/133147694)
  • 使用名稱字串 (例如 @Parameters(name = "size={0},depth={1}")) 的 @Parameterized 基準資料現在輸出 JSON 輸出中每個基準的參數名稱和值 (b/132578772)
• 模擬測試模式 (b/138785848)
  • 新增「模擬測試」模式，讓每個基準迴圈僅執行一次，可檢查是否有錯誤/當機而未評估測量結果。舉例來說，如果預先提交基準的執行速度很快，系統就會進行檢查，確認基準不會中斷。

API 變更

• 模組結構已變更，請分割程式庫 (b/138451391)
  • benchmark:benchmark-junit4 包含具有 JUnit 依附元件 (AndroidBenchmarkRunner 和 BenchmarkRule) 的類別，且兩者已移至 androidx.benchmark.junit4 套件
  • benchmark:benchmark-common 包含其餘邏輯，包括 BenchmarkState API
  • 這種分割方式可讓資料庫在沒有 JUnit4 API 的情況下支援基準化
• 系統現在會將設定警告視為錯誤，並繼續執行測試 (b/137653596)
  • 這樣做是為了進一步鼓勵準確評估，尤其是在持續整合 (CI) 中
  • 這些錯誤可能會透過檢測引數而傳回。例如：-e androidx.benchmark.suppressErrors "DEBUGGABLE,LOW_BATTERY"

修正錯誤

• 在 Q 裝置上寫入外部儲存空間時，發生錯誤時會出現說明較明確的訊息，並提供解決問題的建議
• 系統會在基準執行期間自動開啟螢幕，而非關閉螢幕

外部貢獻

• 感謝 Sergey Zakharov 改善 JSON 輸出功能及修正螢幕關閉問題！

1.0.0-alpha03 版本

2019 年 7 月 2 日

發布 androidx.benchmark:benchmark:1.0.0-alpha03 和 androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha03。您可以前往這裡查看這個版本包含的修訂項目。

新功能

• 在完整的 JSON 報表中顯示因防止裝置過熱而進入休眠的持續時間 (根據基準測試)。

修正錯誤

• 在執行 Android 外掛程式和 Android 區塊後，不再需要套用 Gradle 外掛程式
• 支援在設有範圍儲存空間的 Android 10 裝置上支援基準報表

1.0.0-alpha02 版本

2019 年 6 月 6 日

發布 androidx.benchmark:1.0.0-alpha02 和 androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha02。您可以前往這裡查看這個版本包含的修訂版本。

請注意，我們會將 JSON 結構定義視為 API。我們計劃採用與其他 API 相同的穩定性限制：在 Beta 版中保持穩定 (使用極少數例外)，並修正最終版本，只有小幅的新增項目和主要變更/移除的部分版本。

API 變更

• 覆寫的 JSON 結構定義。對 JSON 結構定義所做的進一步變更可能只有新增項目會有下列限制：

  • 重新整理結果物件結構，以在未來支援更多指標群組 (b/132713021)
  • 在頂層物件中新增測試執行情境資訊，例如裝置和建構資訊，以及時鐘是否鎖定 (b/132711920)
  • 時間指標名稱中包含「ns」一詞 (b/132714527)
  • 每項已回報的指標 (最大值、中位數、最小值) 會增加額外的統計資料，並移除簡化的「nanos」摘要統計資料 (b/132713851)

• 移除了 XML 輸出 (b/132714414)

• 已從 BenchmarkState.reportData API 中移除過熱保護偵測機制 (b/132887006)

修正錯誤

• 修正了 ./gradlew lockClocks 並未安裝在部分近期的 OS 裝置上 (b/133424037)
• 模擬器的過熱保護偵測機制已停用 (b/132880807)

1.0.0-alpha01 版本

2019 年 5 月 7 日

發布 androidx.benchmark:benchmark:1.0.0-alpha01。您可以前往這裡查看這個版本包含的修訂版本。