Define custom events

System tracing shows you information about processes only at the system level, so it's sometimes difficult to know which of your app or game's methods were executing at a given time relative to system events.

Jetpack provides a tracing API that you can use to label a particular section of code. This information is then reported in traces captured on the device. Macrobenchmark captures traces with custom trace points automatically.

When using the systrace command line tool to capture traces, the -a option is required; without this option, your app's methods will not appear in a system trace report.

Kotlin

To create custom trace events in your code, use the tracing-ktx library. The top-level trace function, in particular, handles the begin and end logic automatically. You can see this in the following code snippet. 
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

To create custom trace events in your code, use the Trace class in the Jetpack tracing library, as shown in the following code snippet.

Note: When you call beginSection() multiple times, calling endSection() ends only the most-recently-called beginSection() method. So, for nested calls, such as those in the following snippet, make sure that you properly match each call to beginSection() with a call to endSection().

Additionally, you cannot call beginSection() on one thread and end it from another thread; you must call both methods on the same thread.

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();
        }
    }
}

There is also an NDK API for custom trace events. You can find out more about using that API for your native code in the Custom trace events in native code documentation.