aliyun_log_dart_sdk 1.1.1

Aliyun Log Service for dart & flutter. You can send your business data to your private SLS Logstore with this sdk.

Aliyun SLS SDK for Dart

package	pub	likes	popularity	pub points
aliyun_log_dart_sdk

阿里云日志服务 SLS 官方插件，当前支持 Android/iOS 数据采集。

使用方式

• 登录 阿里云 SLS 控制台，并创建或获取endpoint、project、logstore、AK 等信息。
• 按照 pub.dev 上面的安装说明，对项目进行配置。
• 使用 endpoint、project、logstore 等信息初始化 SLS Dart SDK。

import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';
  AliyunLogDartSdk? _aliyunLogSdk;

  void _initProducer() async {
    LogProducerConfiguration configuration = LogProducerConfiguration(
        endpoint: 'your endpoint', project: 'your project', logstore: 'your logstore'
    ); // endpoint、project、logstore 后续可动态更新
    configuration.accessKeyId = 'your access key id';
    configuration.accessKeySecret = 'your access key secret';
    configuration.securityToken = 'your access key token'; // 使用 STS 方式获取的 AK 时需要
    _aliyunLogSdk = AliyunLogDartSdk();
    LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);
  }

上报日志

可以通过 addLog 方法上报自定义业务日志。

LogProducerResult code = await _aliyunLogSdk!.addLog({
    'str': 'str value',
    'int': 12,
    'double': 12.12,
    'boolean': true,
    'map': {'key': 'value', 'inntt': 3333},
    'array': ['a1', 'a2'],
    'null': null,
    'content': '中文'
});

仅当 code == LogProducerResult.ok 时才表示 addLog 成功。其他情况下错误码的说明参见后文。

配置参数说明

配置参数定义在 LogProducerConfiguration 类中：

配置参数	参数说明	取值
endpoint	Project 所在地域的入口	一般在 project 的概览页获取，更多参见：服务入口。
project	日志服务的资源管理单元	Project介绍
logstore	日志服务中数据的采集、存储、查询单元	Logstore介绍
accesskeyId	访问日志服务需要使用 AccessKey 用来进行身份验证	AccessKey介绍
accessKeySecret	访问日志服务需要使用 AccessKey 用来进行身份验证	AccessKey介绍
securityToken	访问日志服务需要使用 AccessKey 用来进行身份验证	STS 方式获取的 AK 才需要。AccessKey介绍
debuggable	是否开启调试模式	默认为 false，表示关闭。 当遇到数据采集问题时建议开启。
connectTimeout	网络连接超时时间	默认为 10 秒。一般不建议修改。
sendTimeout	网络发送超时时间	默认为 15 秒。一般不建议修改。
ntpTimeOffset	设备时间与标准时间之差	默认为 0 秒。不建议修改，SDK 已经支持时间自动校正。
maxLogDelayTime	日志时间与本机时间之差	默认为 7 天。超过该值后，会根据 dropDelayLog 参数进行处理。不建议修改。
dropDelayLog	对超过 maxLogDelayTime 日志的处理策略	默认为 false，不丢弃。__time__ 会重置为当前时间。
dropUnauthorizedLog	是否丢弃鉴权失败的日志	默认为 false，不丢弃。
source	__source__ 字段的值	默认为 Android、iOS。
topic	__topic__ 字段的值	无默认值。
_tags	__tag__:xxx:yyy 字段的值	无默认值。需要通过 LogProducerConfiguration.addTag() 或 AliyunLogDartSdk.addTag() 方法设置。
packetLogBytes	每个待发送日志包的大小	整数，取值为1~5242880，单位为字节。默认为1024 * 1024。
packetLogCount	每个待发送日志包中日志数量的最大值	整数，取值为1~4096，默认为1024。
packetTimeout	待发送日志包等待超时时间，超时则会立即发送	整数，单位为毫秒，默认为3000。
persistent	是否开启断点续传功能。	默认为 false。建议开启。
persistentForceFlush	是否每次 addLog 强制刷新，高可靠性场景建议打开	默认为 false。一般不建议打开，对性能会有一定的影响。
persistentFilePath	断点续传 binlog 缓存路径	默认为空字符串。配置的路径需要存在，且不同 AliyunLogDartSdk 实例对应的路径必须不同。
persistentMaxFileCount	持久化文件滚动个数，建议设置成10	默认为 10。
persistentMaxFileSize	每个持久化文件大小	默认为 1 MB。
persistentMaxLogCount	最多缓存的日志数，不建议超过1M	默认为65536。

动态配置参数

SDK 支持对 endpoint、project、logstore、AK 等参数动态更新。

• 更新 endpoit、project、logstore：

await _aliyunLogSdk!.setEndpoint('https://cn-hangzhou.log.aliyuncs.com');
await _aliyunLogSdk!.setProject('yuanbo-test-2');
await _aliyunLogSdk!.setLogstore('test2');

• 更新 AccessKey

// securityToken 为可选值，仅当 AccessKey 是通过 STS 方式获取时必填
await _aliyunLogSdk!.setAccessKey('your accesskey id', 'your accesskey secret', securityToken: 'your accesskey token');

• 更新 source、topic、tag

await _aliyunLogSdk!.setSource('flutter');
await _aliyunLogSdk!.setTopic('flutter-test');
await _aliyunLogSdk!.addTag('tag1', 'value1');
await _aliyunLogSdk!.addTag('tag2', 'value2');

• 其他参数动态配置

LogProducerConfiguration configuration = LogProducerConfiguration();
configuration.dropDelayLog = true;
configuration.dropUnauthorizedLog = true;
// 其他 LogProducerConfiguration 的参数也可通过这种方式设置。
await _aliyunLogSdk!.updateConfiguration(configuration);

注意：AliyunLogDartSdk.updateConfiguration() 不支持动态配置断点续传相关的参数。

设置日志发送回调

SDK 支持设置日志发送回调。日志发送成功或失败时，都会产生对应的回调信息。我们可以通过回调信息来观察 SDK 的运行情况，或者更新 SDK 的参数配置。

_aliyunLogSdk!.setLogCallback((resultCode, errorMessage, logBytes, compressedBytes) {
  // 参数配置错误，需要更新参数
  if (LogProducerResult.parametersInvalid == resultCode) {
    // 如更新 endpoint 配置
    _aliyunLogSdk!.setEndpoint('your endpoint');
    // AK 没有配置，或配置错误也会触发parametersInvalid
    _aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
  }

  // 授权过期，需要更新 AK
  if (LogProducerResult.sendUnauthorized == resultCode) {
    _aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
  }
});

开启断点续传

注意： 断点续传功能的开启时机，必须要在初始化 AliyunLogDartSdk 时决定，sdk 初始化完成后不支持动态修改断点续传相关配置信息。

configuration.persistent = true; // 开启断点续传
configuration.persistentFilePath = 'flutter/demo'; // binlog 缓存目录
configuration.persistentForceFlush = false; // 关闭强制刷新，建议关闭，开启后会对性能产生一定的影响
configuration.persistentMaxFileCount = 10; // 缓存文件数量，默认为 10
configuration.persistentMaxFileSize = 1024 * 1024; // 单个缓存文件的大小，默认为 1MB
configuration.persistentMaxLogCount = 64 * 1024; // 缓存日志的数量，默认为 64K
_aliyunLogSdk = AliyunLogDartSdk();
LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);

错误码说明

错误码	说明	解决方法
ok	成功
invalid	SDK 已销毁或无效	SDK 初始化失败或已销毁（主动调用了destroy()方法）
writeError	数据写入错误	同 sendQuotaError
dropError	缓存已满	磁盘或内存缓存已满，日志无法写入。
sendNetworkError	网络错误	检查网络连接情况
sendQuotaError	Project 写 Quota 已满	Project写入流量已达上限，提工单联系 SLS
sendUnauthorized	AK 授权过期或无效	AK 过期、无效，或AK权限策略配置不正确
sendServerError	服务错误	服务故障
sendDiscardError	数据被丢弃	SDK 会自动重新发送
sendTimeError	与服务器时间不同步	设备时间与服务时间不同步，SDK 会自动修复该问题
sendExitBuffered	SDK 销毁时，缓存数据还没有发出	可能会导致数据丢失，建议开启断点续传功能可避免数据丢失
parametersInvalid	SDK 初始化参数错误	一般是 AK 没有配置，或 endpoint、project、logstore 配置不正确导致的
persistentError	缓存数据写入磁盘失败	缓存文件路径配置不正确，或缓存文件已经写满，或系统磁盘空间不够导致
unknown	未知错误	不太可能出现，如果出现请提 bug