tll_monitor_flutter_sdk #

TLL Flutter 纯 Dart 异常监控采集 SDK，对接 tll-monitor-serve HTTP 协议。

特性 #

• 纯 Dart 实现，无 Android/iOS 原生代码
• 最小接入：传 appId / appSecret / serverUrl 即可
• 自动采集 Flutter Framework 错误、PlatformDispatcher 异步错误、Zone 未捕获异常
• 批量缓冲 + 定时 flush，对齐协议（10 条/包，50KB 上限）
• fatal 级异常走单条实时通道
• 发送失败时 JSONL 本地落盘补发（移动端）
• 提供启停、暂停、flush、用户上下文等控制 API

快速接入 #

1. 添加依赖 #

Pub 发布（pub.flutter-io.cn / 私服）：

dependencies:
  tll_monitor_flutter_sdk: ^1.0.0

GitLab Git 依赖（内网推荐）：

dependencies:
  tll_monitor_flutter_sdk:
    git:
      url: https://gitlab.tianlala.com/commonService/tll-monitor-combine.git
      ref: tll_monitor_flutter_sdk-v1.0.0
      path: tll_monitor_flutter_sdk

本地 path 依赖（开发调试）：

dependencies:
  tll_monitor_flutter_sdk:
    path: ../tll_monitor_flutter_sdk

2. 初始化（最简） #

import 'package:flutter/material.dart';
import 'package:tll_monitor_flutter_sdk/tll_monitor_flutter_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await TllMonitor.init(
    appId: 'order-app',
    appSecret: 'your-secret',
    serverUrl: 'http://127.0.0.1:8085',
  );

  runZonedGuarded(
    () => runApp(const MyApp()),
    (error, stack) => TllMonitorZoneBridge.handle(error, stack),
  );
}

3. 使用完整配置（可选） #

await TllMonitor.init(
  options: TllMonitorOptions(
    appId: 'order-app',
    appSecret: 'your-secret',
    serverUrl: 'http://127.0.0.1:8085',
    env: 'prod',
    appVersion: '1.2.0',
    sourceType: 'flutter', // 也可显式传 android / ios / web
    debugLog: true,
  ),
);

4. 一键启动（推荐） #

await runTllMonitorApp(
  const MyApp(),
  onInitMonitor: () => TllMonitor.init(
    appId: 'order-app',
    appSecret: 'your-secret',
  ),
);

控制 API #

初始化后通过 TllMonitor.instance 控制：

final monitor = TllMonitor.instance;

// 启停与暂停
monitor.enable();
monitor.disable();
monitor.pause();
monitor.resume();
await monitor.flush();

// 用户与上下文
monitor.setUserId('10001');
monitor.setDeviceId('device-001');
monitor.setTraceId('trace-abc');
monitor.setPagePath('/home');
monitor.setNetworkType('wifi');
monitor.setGlobalTags(['channel:appstore']);

// 手动上报
monitor.report(
  Exception('payment failed'),
  stackTrace: StackTrace.current,
  tags: ['payment'],
);

// HTTP 慢请求采集（默认 >= 5 秒才上报）
final client = TllMonitor.createHttpClient();
final response = await client.get(Uri.parse('https://api.example.com/order/list'));

// 查看状态
final status = monitor.status;
print(status.queueSize);

// 应用退出
await TllMonitor.dispose();

默认配置 #

上报传输（MQTT 优先 + HTTP 兜底） #

默认走 MQTT，发送失败时自动回落 HTTP，Topic 与 Payload 遵循接入协议：

await TllMonitor.init(
  options: TllMonitorOptions(
    appId: 'order-app',
    appSecret: 'your-secret',
    serverUrl: 'http://127.0.0.1:8085', // HTTP 兜底地址
    mqttBrokerUrl: 'tcp://127.0.0.1:1883',
    mqttUsername: 'mqtt',
    mqttPassword: 'your-mqtt-password',
    reportTransport: MonitorReportTransport.mqttWithHttpFallback,
  ),
);

说明：

• 未配置 mqttBrokerUrl 时，SDK 会直接使用 HTTP 上报
• Web 平台无 MQTT 能力，会自动走 HTTP 兜底
• 仅 HTTP：reportTransport: MonitorReportTransport.httpOnly
• 仅 MQTT：reportTransport: MonitorReportTransport.mqttOnly

HTTP 采集规则 #

HTTP 慢请求与失败采集 #

SDK 提供 TllMonitorHttpClient，自动计时并按规则上报：

// 推荐：替换业务 HTTP Client
final client = TllMonitor.createHttpClient();
final response = await client.get(Uri.parse('https://api.example.com/users'));

// 自定义阈值（6 秒）
await TllMonitor.init(
  options: TllMonitorOptions(
    appId: 'order-app',
    appSecret: 'your-secret',
    httpSlowThresholdMillis: 6000,
  ),
);

// 手动上报（如使用 dio 等第三方库）
final stopwatch = Stopwatch()..start();
try {
  await dio.get('/orders');
} finally {
  stopwatch.stop();
  TllMonitor.captureHttp(
    url: '/orders',
    method: 'GET',
    costMs: stopwatch.elapsedMilliseconds,
    responseCode: 200,
  );
}

上报字段包含 url、http_method、response_code、cost_ms 等，与服务端协议一致。

协议对齐 #

MQTT（默认）：

• Topic：monitor/exception/{appId}/{sourceType} / .../fatal
• Payload：单条事件或批量 { app_id, source_type, client_time, events }
• 限制：单包最多 10 条、不超过 50KB

HTTP（兜底）：

• POST /monitor/exception/single
• POST /monitor/exception/batch

HTTP 请求头：

• X-App-Id
• X-App-Secret

开发与发布 #

cd tll_monitor_flutter_sdk
flutter pub get
flutter analyze
flutter test
dart pub publish --dry-run   # 发布前校验

正式发布步骤见 PUBLISHING.md。

注意事项 #

• appId / appSecret 需与 tll-monitor-serve 的 tll.monitor.exception.collect.allowed-apps 配置一致
• SDK 采集链路失败不会影响业务异常抛出
• Web 平台暂不启用本地落盘（无 dart:io）