Definir eventos personalizados

O rastreamento do sistema mostra informações sobre processos apenas no nível do sistema. Por isso, às vezes é difícil saber quais métodos do seu app ou jogo estavam sendo executados em determinado momento em relação aos eventos do sistema.

O Jetpack oferece uma API de rastreamento que pode ser usada para rotular determinada seção de código. Essas informações são relatadas nos rastreamentos capturados no dispositivo. O Macrobenchmark captura rastros com pontos personalizados automaticamente.

Ao usar a ferramenta de linha de comando Systrace para capturar traces, a opção -a é obrigatória. Sem essa opção, os métodos do app não aparecerão em um relatório de rastreamento do sistema.

Kotlin

Para criar eventos de rastreamento personalizados no código, use a biblioteca trace-ktx. A função de rastreamento de nível superior, em particular, processa a lógica inicial e final automaticamente. Veja isso no snippet de código a seguir. 
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

Para criar eventos de rastreamento personalizados no código, use a classe Trace na biblioteca de rastreamento do Jetpack, conforme mostrado no snippet de código a seguir.

Observação: quando beginSection() é chamado várias vezes, chamar endSection() encerra apenas o método beginSection() chamado mais recentemente. Por esse motivo, combine corretamente cada chamada de beginSection() com uma chamada de endSection() para chamadas aninhadas, como as do snippet a seguir.

Além disso, não é possível chamar beginSection() em uma linha de execução e depois encerrá-lo em outra. É preciso chamar os dois métodos na mesma linha de execução.

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

Há também uma API NDK para eventos de rastreamento personalizados. Para saber mais sobre como usar essa API no código nativo, consulte a documentação Eventos de rastreamento personalizado em código nativo.