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

OpenTelemetry for Dart

本仓库旨在成为OpenTelemetry项目的Dart实现，长期目标是开源。

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

开始使用

首先，你需要配置至少一个导出器。导出器决定了你收集到的跨度会发生什么。 当前选项包括：

跨度导出器

CollectorExporter

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

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

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

ConsoleExporter

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

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

final exporter = otel_sdk.ConsoleExporter();

跨度处理器

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

BatchSpanProcessor

BatchSpanProcessor 每个区间最多收集2048个跨度，并在定时器上执行提供的导出器。

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

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

SimpleSpanProcessor

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

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

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

跟踪提供者

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

import 'package:opentelemetry_sls/sdk.dart' as otel_sdk;
import 'package:opentelemetry_sls/api.dart';

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

// 每5秒向收集器发送跨度
final provider = otel_sdk.TracerProviderBase(processors: [processor]);

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

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

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

带有浏览器性能特性的跟踪提供者

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

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

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');

// 或者，这些跟踪提供者也可以注册为全局。
registerGlobalTracerProvider(provider);
final tracer = 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();
  });
}