Flutter性能追踪插件tracer的使用

Flutter性能追踪插件tracer的使用

tracer 是一个现代化、简单且易于实现的日志记录框架，适用于Dart语言。

该插件应该可以在所有Flutter平台上运行，包括Web。它还经过了纯Dart环境的测试。

使用

基本的 Tracer 对象可以通过调用其构造函数来创建：

var t = Tracer("example");

第一个键称为 ‘section’，用于标识此日志记录器。字符串可以是你想要的任何内容，不会影响功能。

你可以调用以下的日志记录方法之一：

t.debug("This is a debug message");
t.info("This is an info message");
t.warn("This is a warning message");
t.error("This is an error message");
t.fatal("This is a fatal message");

如果你已经按照步骤操作，你可能会注意到当你调用这些方法时，什么都没有发生。这是因为你还必须添加一个处理程序来处理日志事件。更多内容请参阅 处理程序。

在日志方法中还有其他一些事情可以做。更多信息请参阅 扩展日志记录。

默认情况下，debug级别的日志将被隐藏。要设置自定义的最低级别，可以在 Tracer 构造函数中设置 logLevel 为 TracerLevel 的值，如 TracerLevel.info（默认）。

处理程序

该库本身不会对发送的日志消息执行任何操作。你必须自行指定会发生什么。

不用担心，你不必重新发明轮子；该包具有一些内置的输出处理程序，可以帮助你。

要嵌入一个处理程序，只需将参数添加到 Trace 对象的构造函数中：

var tracer = Tracer("example", handlers: [
    TracerConsoleHandler(),
    TracerFileHandler(Directory("./logs"))
]);

列表将从上到下处理。第一个处理程序将首先评估，依此类推。两个最突出的内置处理程序是：

1. TracerConsoleHandler

   • 这是你可能最常使用的处理程序。它将生成的日志输出到系统的终端。
   • 默认情况下，输出将着色。要禁用颜色，将 useColors 设置为 false。
   • 它默认使用 Dart 的 print 函数，因此完全兼容 Flutter 平台的输出。要使用标准的 stdout 和 stderr，将 useStderr 设置为 true。

2. TracerFileHandler

   • 此处理程序将输出到文件。默认情况下，它会在给定目录中每天创建一个新文件。
   • 要使用固定名称，将属性 customName 设置为有效的文件名字符串。
   • 传递的目录如果不存在，将会自动创建。但它应该是有效的路径。

自定义处理程序

创建自己的处理程序很简单。你只需要创建一个新的类，继承预定义的 TracerHandler 类。

class TracerTestHandler extends TracerHandler {
    @override
    void handle(TracerEventData data) {
        print(data.body);
    }
}

之后，你可以以同样的方式注册它，就像注册预定义的一样。

var tracer = Tracer("example", handlers: [
    TracerTestHandler()
]);

替代方案

如果你不需要在每次创建新的日志事件时都得到通知，你可能不想创建整个处理程序并自己跟踪完整的日志历史。

幸运的是，你可以通过只读取你的 Tracer 对象的一个值来访问历史。你可以选择访问文本表示形式，或者获取所有以前的 TracerEventData 列表。

tracer.logs             // 列表中包含 TracerEventData
tracer.logsGenerated    // 字符串表示形式

过滤器

过滤器的构建方式与处理程序非常相似。它们在日志事件触发之前询问是否应该处理。这在第三方模块控制日志记录器但你不希望输出所有内容的情况下很有用。

没有内置的过滤器，如果你需要一个，你必须自己创建一个。

开始时，创建一个继承内置的 TracerFilter 类的新类，并实现你的逻辑：

class TracerTestFilter extends TracerFilter {
    @override
    bool handle(TracerEventData data) {
        return data.body.contains("happy");
    }
}

这次的 handle 函数必须返回一个布尔值，确定事件是否会被处理。如果返回 false，则事件将被忽略。

要添加你的过滤器，你需要像这样将其添加到构造函数中：

var tracer = Tracer("example", filters: [
    TracerTestFilter()
]);

过滤器将从上到下处理。如果一个过滤器返回 false，后续的过滤器将不会被评估。

扩展日志记录

你还可以向你的日志请求添加描述、错误和堆栈跟踪。

要使用描述，只需在日志函数的工具调用中添加 description 属性。多行字符串也是支持的。

t.info("This will have a description", description: "I AM THE DESCRIPTION!");

输出如下：

[2024-10-20 17:12:37 +0200] Info : example: This will have a description
                            |> I AM THE DESCRIPTION!

要添加错误/异常和堆栈跟踪报告，你可以向函数调用中添加 error 和 stack 属性。这仅适用于级别为 TracerLevel.warn 及以上的情况。

try {
    throw Exception("This is an error");
} catch (e, s) {
    t.fatal("This is a stack trace",
        error: e, stack: s);
}

输出如下：

[2024-10-20 17:59:21 +0200] Fatal: example: This is a stack trace
                            |- Exception: This is an error
                            |- example\tracer_example.dart 31:5  main

示例代码

以下是一个完整的示例代码，展示了如何使用 tracer 插件：

import 'dart:io';
import 'dart:async';

import 'package:tracer/tracer.dart';

void main() {
  var t = Tracer("example", logLevel: TracerLevel.debug, forceUtc: true, handlers: [
    TracerConsoleHandler(),
    TracerFileHandler(File("logs/test.log"), append: false),
  ]);
  
  t.debug("This is a debug message");
  t.info("This is an info message");
  t.warn("This is a warning message");
  t.error("This is an error message");
  t.fatal("This is a fatal message");

  print("-----");

  t.info("This will have a description", description: "I AM THE DESCRIPTION!");
  t.warn("Multiline description", description: "Line 1\nLine 2\nLine 3");

  print("-----");

  try {
    throw Exception("This is an exception");
  } catch (e) {
    t.error("This is an error with an exception", error: e);
  }
  try {
    throw Exception("This is a second exception");
  } catch (e, s) {
    t.fatal("This is an error with an exception and stack trace",
        error: e, stack: s);
  }

  runZonedGuarded(() {
    throw Exception("This is an exception in a zone");
  }, (error, stack) {
    t.fatal(
        "This is an error with an exception and stack trace, triggered by a zone",
        error: error,
        stack: stack);
  });

  print("-----");

  t.info("The next message will be shown in 5 seconds");
  Future.delayed(Duration(seconds: 5), () {
    t.info("This message was delayed by 5 seconds");
  });
}