Flutter分布式追踪插件opentelemetry_dart的使用

OpenTelemetry for Dart

从OpenTelemetry fork而来以添加JSON报告器。

此项目旨在成为OpenTelemetry项目的Dart实现，并长期目标是开源。

所有贡献和设计应遵循OpenTelemetry规范，以便与所有其他语言保持一致。

开始使用

首先，你需要配置至少一个导出器。导出器决定了你收集到的跨度将如何处理。 当前选项有：

跨度导出器

CollectorExporter

CollectorExporter 需要 opentelemetry-collector 实例的跟踪收集器的Uri。

import 'package:opentelemetry_dart/sdk.dart' as otel_sdk;

final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));

ConsoleExporter

ConsoleExporter 没有要求，也没有配置选项。

import 'package:opentelemetry_dart/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();

跨度处理器

接下来，你需要至少一个跨度处理器。跨度处理器负责收集你创建的跨度并将它们传递给导出器。 当前选项有：

BatchSpanProcessor

BatchSpanProcessors 每个间隔最多收集2048个跨度，并按定时器执行提供的导出器。

import 'package:opentelemetry_dart/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();
final processor = otel_sdk.BatchSpanProcessor(exporter, scheduledDelay: 10000);

SimpleSpanProcessor

SimpleSpanProcessor 没有配置选项，并在每个跨度关闭时执行导出器。

import 'package:opentelemetry_dart/sdk.dart' as otel_sdk;

final exporter = otel_sdk.ConsoleExporter();
final processor = otel_sdk.SimpleSpanProcessor(exporter);

跟踪提供器

跟踪提供器注册你的跨度处理器，并负责管理任何跟踪器。

import 'package:opentelemetry_dart/sdk.dart' as otel_sdk;

final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));
final processor = otel_sdk.BatchSpanProcessor(exporter);

// 每5秒发送跨度到收集器
final provider = otel_sdk.TracerProvider([processor]);

// 可选地，可以注册多个处理器
final provider = otel_sdk.TracerProvider([
  otel_sdk.BatchSpanProcessor(otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'))),
  otel_sdk.SimpleSpanProcessor(otel_sdk.ConsoleExporter())
]);

// 注册跟踪提供器作为全局，以便MSDK中间件可以访问它。
otel_sdk.registerGlobalTracerProvider(provider);

final tracer = provider.getTracer('instrumentation-name');
// 或者
final tracer = otel_sdk.globalTracerProvider.getTracer('instrumentation-name');

带浏览器性能功能的跟踪提供器

还提供了一个特定于Web的跟踪提供器。该跟踪提供器利用浏览器的性能API提供了可配置的选项。

import 'package:opentelemetry_dart/sdk.dart' as otel_sdk;
import 'package:opentelemetry_dart/web_sdk.dart' as web_sdk;

final exporter = otel_sdk.CollectorExporter(Uri.parse('https://my-collector.com/v1/traces'));
final processor = otel_sdk.BatchSpanProcessor(exporter);

// 此提供器配置为创建使用浏览器的性能API而不是Dart的DateTime类来确定跨度时间戳的跟踪器。
final provider = web_sdk.WebTracerProvider(
  processors: [processor],
  timeProvider: web_sdk.WebTimeProvider()
);

// 此跟踪器已配置为使用浏览器的性能API来确定其创建的任何跨度的时间戳。
final tracer = provider.getTracer('instrumentation-name');

// 或者，这些跟踪提供器也可以全局注册。
otel_sdk.registerGlobalTracerProvider(provider);
final tracer = otel_sdk.globalTracerProvider.getTracer('instrumentation-name');

重要提示：使用此跟踪提供器生成的跨度时间戳可能不准确，如果执行系统处于休眠状态。更多信息见此处。

收集跨度

要开始一个跨度，可以在跟踪器上执行 startSpan 并传入你正在跟踪的内容的名称。完成后，调用跨度上的 end 方法。

final span = tracer.startSpan('doingWork');
...
span.end();

要创建子跨度，必须将父跨度设置为“当前”，并在 withContext 中执行工作。

final checkoutSpan = tracer.startSpan('checkout');
withContext(setSpan(Context.current, checkoutSpan), () {
  final ringUpSpan = tracer.startSpan('ringUp');
  ...
  ringUpSpan.end();
  final receiveSpan = tracer.startSpan('receiveCash');
  ...
  receiveSpan.end();
  final returnSpan = tracer.startSpan('returnChange');
  ...
  returnSpan.end();
});
checkoutSpan.end();

为了避免在其他函数中传递跨度作为参数，你可以使用 Context.current.span 获取当前跨度。

doWork() {
  Span parentSpan = Context.current.span;

  Context.current.withSpan(parentSpan).execute(() {
    Span span = tracer.startSpan('doWork');
    ...
    span.end();
  });
}

开发

为了生成protobuf定义，你必须安装并使protoc在你的路径中可用。

https://github.com/protocolbuffers/protobuf/releases