定義自訂事件

系統追蹤只會顯示系統層級程序的相關資訊，因此有時很難知道在系統事件相關的特定時間，執行的是哪個應用程式或遊戲的方法。

Jetpack 提供追蹤 API，可用來為特定程式碼區段加上標籤。這項資訊會記錄在從裝置上擷取的追蹤記錄中。Macrobenchmark 會自動使用自訂追蹤點擷取追蹤記錄。

使用 Systrace 指令列工具擷取追蹤記錄時，需要使用 -a 選項；沒有這個選項，應用程式的方法就不會顯示在系統追蹤記錄報表中。

Kotlin

如要在程式碼中建立自訂追蹤事件，請使用 tracing-ktx 程式庫。特別的是，頂層 trace 函式會自動處理開始與結束邏輯。下列程式碼片段說明了這項功能。

class MyAdapter : RecyclerView.Adapter<MyViewHolder>() {
    override fun onCreateViewHolder(parent: ViewGroup,
            viewType: Int): MyViewHolder {
        trace("MyAdapter.onCreateViewHolder") {
            MyViewHolder.newInstance(parent)
        }
    }

    override fun onBindViewHolder(holder: MyViewHolder, position: Int) {
        trace("MyAdapter.onBindViewHolder") {
            trace("MyAdapter.queryDatabase")
                val rowItem = queryDatabase(position)
                dataset.add(rowItem)
            }
            holder.bind(dataset[position])
        }
    }
}

Java

如要在程式碼中建立自訂追蹤事件，請使用 Jetpack 追蹤程式庫中的 Trace 類別，如以下程式碼片段所示。

注意：如果多次呼叫 beginSection()，則呼叫 endSection() 只會結束最近呼叫的 beginSection() 方法。因此，如果是巢狀呼叫 (例如下列程式碼片段中的呼叫)，請務必為每個 beginSection() 呼叫正確搭配一個 endSection() 呼叫。

此外，在一個執行緒呼叫 beginSection()，無法從另一個執行緒結束，您必須在同一個執行緒上呼叫這兩個方法。

public class MyAdapter extends RecyclerView.Adapter<MyViewHolder> {
    @Override
    public MyViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
        Trace.beginSection("MyAdapter.onCreateViewHolder");
        MyViewHolder myViewHolder;
        try {
            myViewHolder = MyViewHolder.newInstance(parent);
        } finally {
            // In try and catch statements, always call "endSection()" in a
            // "finally" block. That way, the method is invoked even when an
            // exception occurs.
            Trace.endSection();
        }
        return myViewHolder;
    }

   @Override
    public void onBindViewHolder(MyViewHolder holder, int position) {
        Trace.beginSection("MyAdapter.onBindViewHolder");
        try {
            try {
                Trace.beginSection("MyAdapter.queryDatabase");
                RowItem rowItem = queryDatabase(position);
                dataset.add(rowItem);
            } finally {
                Trace.endSection();
            }
            holder.bind(dataset.get(position));
        } finally {
            Trace.endSection();
        }
    }
}

另外還有用於自訂追蹤事件的 NDK API。如要進一步瞭解如何在原生程式碼中使用這個 API，請參閱「原生程式碼中的自訂追蹤事件」說明文件。