Naar console

Add custom monitoring for specific app code

You can create custom traces to monitor performance data associated with specific code in your app. With a custom trace, you can measure how long it takes your app to complete a specific task or set of tasks, for example loading a set of images or querying your database. The default metric for a custom trace is its duration, but you can add custom metrics, as well.

In your code, you define the beginning and the end of a custom trace using the APIs provided by the Performance Monitoring SDK. For Android apps, you can also monitor specific methods using the @AddTrace annotation.

Traces can also be started after they've been created, and they are thread safe.

Note the following:

  • An app can have multiple custom traces.
  • More than one custom trace can run at the same time.
  • Names for custom traces and custom metrics must meet the following requirements: no leading or trailing whitespace, no leading underscore (_) character, and max length is 32 characters.

Default attributes, custom attributes, and custom metrics

For custom traces, Performance Monitoring automatically logs the default attributes that are collected for any trace (applicable metadata like app version, country, device, browser, etc.) so that you can filter the data in the Firebase console. For custom traces, you can also add and monitor custom attributes (such as, game level or user properties).

You can further configure a custom trace to record custom metrics for performance-related events that occur within the trace's scope. For example, you can create a custom metric for the number of cache hits and misses or the number of times that the UI becomes unresponsive for a noticeable period of time. The data for these custom metrics display in the Firebase console alongside the default metrics for the trace.

Add custom traces and custom metrics

  1. Import these Performance Monitoring classes at the top of your .java or .kt file:

    import com.google.firebase.perf.FirebasePerformance;
    import com.google.firebase.perf.metrics.Trace;
    
  2. To start and stop a custom trace, wrap the code that you want to trace with lines of code similar to the following (this example uses a custom trace name of test_trace):

    Java

    Trace myTrace = FirebasePerformance.getInstance().newTrace("test_trace");
    myTrace.start();
    
    // code that you want to trace
    
    myTrace.stop();
    

    Learn more about the API for custom traces.

    Kotlin

    val myTrace = FirebasePerformance.getInstance().newTrace("test_trace")
    myTrace.start()
    
    // code that you want to trace
    
    myTrace.stop()
    

    Learn more about the API for custom traces.

  3. To add a custom metric, add a line of code similar to the following each time that the event occurs. For example, this custom metric counts performance-related events that occur in your app, such as cache hits and misses (using example event names of item_cache_hit and item_cache_miss and an increment of 1).

    Java

    Trace myTrace = FirebasePerformance.getInstance().newTrace("test_trace");
    myTrace.start();
    
    // code that you want to trace (and log custom metrics)
    Item item = cache.fetch("item");
    if (item != null) {
        myTrace.incrementMetric("item_cache_hit", 1);
    } else {
        myTrace.incrementMetric("item_cache_miss", 1);
    }
    
    myTrace.stop();
    

    Kotlin

    val myTrace = FirebasePerformance.getInstance().newTrace("test_trace")
    myTrace.start()
    
    // code that you want to trace (and log custom metrics)
    val item = cache.fetch("item")
    if (item != null) {
        myTrace.incrementMetric("item_cache_hit", 1)
    } else {
        myTrace.incrementMetric("item_cache_miss", 1)
    }
    
    myTrace.stop()
    

(Optional) Monitor specific methods using @AddTrace

Android apps also support the @AddTrace annotation to create custom traces. Using this feature, the trace starts at the beginning of the specified method and stops when the method completes, including anything invoked by the method.

For example, to create a custom trace called onCreateTrace that runs when the onCreate() method is called, use code similar to the following:

Java

@Override
@AddTrace(name = "onCreateTrace", enabled = true /* optional */)
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
}

Kotlin

@AddTrace(name = "onCreateTrace", enabled = true /* optional */)
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
}

Monitor custom traces and metrics in the console

  1. In the Firebase console, go to the Performance dashboard.

  2. Click the On device tab, then you can:

    • View a quick report of the collected data for all your traces.

    • Click a specific trace to review the trace's data in more detail.

    • Use the Filteradd button in the top-left of the dashboard to perform basic filtering of the data by attribute.

  3. If you click a specific trace, the console displays an overview of the collected data on metric cards, including the default Duration metric and any other custom metrics that you've configured for the custom trace.

    • Use the options in the top-right of the dashboard to view the duration data as aggregated, over time, or for each version of your app.

    • Use the Filteradd button in the top-left of the dashboard to perform basic filtering of the data by attribute.

  4. For any metric, click View more to review more in-depth information about the collected data and to use richer analysis features. For example, you can filter and segment the data by attribute and view the data in the context of an app-usage session.

    The following section describes the available features of the in-depth trace report.

View more details on trace samples

You can deep dive into segments of specific traces or network requests in the Firebase console. A random sampling of recorded sessions shows the following information:

an image of the Firebase Performance Monitoring sessions page

  • CPU: How much user time and system time your app consumes.

  • Memory: How much heap memory your app uses. Heap memory is the memory used for dynamic allocations, including objects created, objects deallocated, and objects that the app is actively using.

  • Individual information: Detailed information about a single instance of a trace or network request, including start time, end time, duration, request size, and response size.

  • Concurrent instances: Information about traces or network requests that happened at the same time.

  • Device attributes: Information about the device, including app version, model, OS version, radio, and custom attributes.

To see these detailed samples in the Firebase console, you can either:

  • Open one of your app's traces or network requests, then click See sessions.

  • Click the link for an attribute's sessions from the specific attribute.

an image of the Firebase Performance Monitoring trace with a link to sessions

Filter sessions by percentile

The sessions that Performance Monitoring collects are distributed into percentiles for each metric. Sessions in lower percentile ranges have a lower value for the metric than sessions in higher percentile ranges.

To filter the available sessions by percentile, use the percentiles dropdown above the sessions details.

an image of the Firebase Performance Monitoring sessions page

Next Steps