为特定应用代码添加自定义监控

Performance Monitoring 会收集跟踪记录，帮助您监控应用的性能。跟踪记录是两个时间点之间在应用中捕获的性能数据的报告。

您可以创建自己的跟踪记录来监控与应用中的特定代码相关联的性能数据。借助自定义代码跟踪记录，您可以衡量应用完成一项特定任务或一组任务（例如加载一组图像或查询数据库）所需的时间。

自定义代码跟踪记录的默认指标是其“时长”（此跟踪记录的开始点和停止点之间的时间），但您也可以添加自定义指标。

在代码中，您可以使用 Performance Monitoring SDK 提供的 API 指定自定义代码跟踪记录的开始和结束。对于 Android 应用，您还可以使用 @AddTrace 注释来监控特定方法。自定义代码跟踪记录可在创建后随时启动，并且是线程安全的。

由于这些跟踪记录收集的默认指标为“时长”，因此它们有时被称为“时长跟踪记录”。

您可以在“性能”信息中心底部的跟踪记录表中的“自定义跟踪记录”子标签中查看这些跟踪记录中的数据（在本页下文中详细了解如何使用控制台）。

默认特性、自定义特性和自定义指标

对于自定义代码跟踪记录，Performance Monitoring 会自动记录默认特性（应用版本、国家/地区、设备等常见元数据），使您可以在 Firebase 控制台中过滤跟踪记录的数据。您还可以添加和监控自定义特性（例如游戏关卡或用户属性）。

您可以进一步配置自定义代码跟踪记录，以记录其范围内发生的性能相关事件的自定义指标。例如，您可以创建一个自定义指标，以统计缓存命中和未命中的次数，或者统计界面较长时间无响应的次数。

自定义特性和自定义指标会与跟踪记录的默认特性和默认指标一起显示在 Firebase 控制台中。

添加自定义代码跟踪记录

使用 Performance Monitoring Trace API 添加自定义代码跟踪记录以监控特定应用代码。

请注意以下几点：

一个应用可以有多个自定义代码跟踪记录。
多个自定义代码跟踪记录可以同时运行。
自定义代码跟踪记录的名称必须符合以下要求：没有前导空格或尾随空格、没有前导下划线 (_) 字符，长度上限为 100 个字符。
自定义代码跟踪记录支持添加自定义指标和自定义特性。

如需启动和停止自定义代码跟踪记录，请使用类似于以下内容的几行代码封装要跟踪的代码（该示例使用自定义跟踪记录名称 test_trace）：

Java

// Import these Performance Monitoring classes at the top of your `.java` file
import com.google.firebase.perf.FirebasePerformance;
import com.google.firebase.perf.metrics.Trace;

Trace myTrace = FirebasePerformance.getInstance().newTrace("test_trace");
myTrace.start();

// code that you want to trace

myTrace.stop();MainActivity.java

Kotlin+KTX

// Import these Performance Monitoring classes at the top of your `.kt` file
import com.google.firebase.perf.FirebasePerformance;
import com.google.firebase.perf.metrics.Trace;

val myTrace = Firebase.performance.newTrace("test_trace")
myTrace.start()

// code that you want to trace

myTrace.stop()MainActivity.kt

（可选）使用 @AddTrace 监控特定方法

Android 应用还支持使用 @AddTrace 注释对自定义代码跟踪记录进行插桩。使用此功能时，跟踪记录会在指定方法开始时启动，并在方法完成时停止（包括该方法调用的任何内容）。

例如，您可以创建一个在调用 onCreate() 方法时运行的名为 onCreateTrace 的自定义代码跟踪记录。

Java

// Import these Performance Monitoring classes at the top of your `.java` file
import com.google.firebase.perf.FirebasePerformance;
import com.google.firebase.perf.metrics.AddTrace;

// Add the `@AddTrace` annotation above the method you want to trace
@Override
@AddTrace(name = "onCreateTrace", enabled = true /* optional */)
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
}MainActivity.java

Kotlin+KTX

// Import these Performance Monitoring classes at the top of your `.kt` file
import com.google.firebase.perf.FirebasePerformance;
import com.google.firebase.perf.metrics.AddTrace;

// Add the `@AddTrace` annotation above the method you want to trace
@AddTrace(name = "onCreateTrace", enabled = true /* optional */)
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
}MainActivity.kt

将自定义指标添加到自定义代码跟踪记录中

使用 Performance Monitoring Trace API 将自定义指标添加到自定义代码跟踪记录中。

请注意以下几点：

自定义特性的名称必须符合以下要求：没有前导空格或尾随空格、没有前导下划线 (_) 字符，长度上限为 100 个字符。
每个自定义代码跟踪记录最多可记录 32 个指标（包括默认时长指标）。

如需添加自定义指标，请在每次发生事件时添加类似于以下内容的一行代码。例如，此自定义指标会统计应用中发生的与性能相关的事件，比如说缓存命中或未命中（使用示例事件名称 item_cache_hit 和 item_cache_miss，以 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();MainActivity.java

Kotlin+KTX

val myTrace = Firebase.performance.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()MainActivity.kt

为自定义代码跟踪记录创建自定义特性

使用 Performance Monitoring Trace API 将自定义特性添加到自定义代码跟踪记录中。

如需使用自定义特性，请向您的应用添加定义该特性的代码，并将其与特定自定义代码跟踪记录相关联。您可以在跟踪记录开始和结束之间的任何时间设置自定义特性。

请注意以下几点：

自定义特性的名称必须符合以下要求：没有前导空格或尾随空格、没有前导下划线 (_) 字符，长度上限为 32 个字符。
每个自定义代码跟踪记录最多可记录 5 个自定义特性。
您不应使用包含的信息可让 Google 识别出个人身份的自定义特性。
详细了解此准则
收集用户数据：Performance Monitoring 不会收集任何个人身份信息 (PII)，例如姓名、电子邮件地址或电话号码。开发者可以通过针对自定义代码跟踪记录创建自定义特性来使用 Performance Monitoring 收集其他数据。通过 Performance Monitoring 收集的此类数据不应包含可让 Google 识别出个人身份的信息。

下面是不含个人身份信息的日志消息示例：
```
trace.putAttribute("experiment", "A");
```
下面是包含个人身份信息的示例（请勿在您的应用中使用此类自定义特性）：
```
trace.putAttribute("email", user.getEmailAddress());
```
任何暴露个人身份信息的数据一律会被删除，恕不另行通知。

Java

Trace trace = FirebasePerformance.getInstance().newTrace("test_trace");

// Update scenario.
trace.putAttribute("experiment", "A");

// Reading scenario.
String experimentValue = trace.getAttribute("experiment");

// Delete scenario.
trace.removeAttribute("experiment");

// Read attributes.
Map<String, String> traceAttributes = trace.getAttributes();MainActivity.java

Kotlin+KTX

Firebase.performance.newTrace("test_trace").trace {
    // Update scenario.
    putAttribute("experiment", "A")

    // Reading scenario.
    val experimentValue = getAttribute("experiment")

    // Delete scenario.
    removeAttribute("experiment")

    // Read attributes.
    val traceAttributes = this.attributes
}MainActivity.kt

跟踪、查看和过滤性能数据

在信息中心内跟踪特定指标

要了解关键指标的趋势如何，请将这些指标添加到“性能”信息中心顶部的指标板中。您可以通过查看逐周变化情况来快速识别回归问题，或者确认近期的代码更改是否改善了性能。

Firebase Performance Monitoring 信息中心中的指标板的图片

如需将指标添加到指标板，请转到 Firebase 控制台中的“性能”信息中心，然后点击“信息中心”标签页。点击一张空白指标卡片，然后选择一个要添加到指标板的现有指标。在填充了信息的指标卡片上点击可查看更多选项，例如替换或移除指标。

该指标板以图表形式以及数值百分比更改的形式显示一段时间内收集的指标数据。

详细了解如何使用信息中心。

查看跟踪记录及其数据

要查看您的跟踪记录，请转到 Firebase 控制台中的“性能”信息中心，向下滚动到跟踪记录表，然后点击相应的子标签页。该表会针对每个跟踪记录显示一些热门指标，您甚至可以按特定指标的百分比变化对该列表进行排序。

点击跟踪记录表中的跟踪记录名称后，即可点击各个相关屏幕以浏览跟踪记录并深入了解感兴趣的指标。在大多数页面上，您可以使用过滤按钮（屏幕左上角）按特性过滤数据，例如：

按特性过滤 Firebase Performance Monitoring 数据的图像

按“应用版本”过滤可查看有关过去版本或最新版本的数据
按“设备”过滤可了解旧设备处理应用的方式
按“国家/地区”过滤可确保您的数据库位置不会影响特定区域

详细了解如何查看跟踪记录的数据。

后续步骤

详细了解如何使用特性来检查性能数据。
详细了解如何在 Firebase 控制台中跟踪性能问题。

查看用户会话的详细报告，通过该报告您可以在同一个会话期间收集的其他跟踪记录的时间轴上下文中查看特定跟踪记录。