Google is committed to advancing racial equity for Black communities. See how.

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.

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 100 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. Each custom trace can record up to 32 metrics, including the default duration metric and any additional custom metrics.

Add custom traces and custom metrics

Use the Trace API to add custom traces and custom metrics to monitor specific application code.

  1. To start and stop a custom trace, wrap the code that you want to trace with lines of code similar to the following:

    const trace = perf.trace('CUSTOM_TRACE_NAME');
    // code that you want to trace

    Learn more about the API for custom traces.

  2. 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.

    async function getInventory(inventoryIds) {
      const trace = perf.trace('inventoryRetrieval');
      // Tracks the number of IDs fetched (the metric could help you to optimize in the future)
      trace.incrementMetric('numberOfIds', inventoryIds.length);
      // Measures the time it takes to request inventory based on the amount of inventory
      const inventoryData = await retrieveInventory(inventoryIds);
      return inventoryData;

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 page load traces (and any custom traces you've added).

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

    • Use the Filter 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.

    • Use the options in the top-right of the dashboard to view data as aggregated or over time.

    • Use the Filter 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.

Next Steps