aliyun_log_dart_sdk

Description:

aliyun log dart 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);
}

copied to clipboard
上报日志
可以通过 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': '中文'
});
copied to clipboard
仅当 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');
copied to clipboard

更新 AccessKey

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

更新 source、topic、tag

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

其他参数动态配置

LogProducerConfiguration configuration = LogProducerConfiguration();
configuration.dropDelayLog = true;
configuration.dropUnauthorizedLog = true;
// 其他 LogProducerConfiguration 的参数也可通过这种方式设置。
await _aliyunLogSdk!.updateConfiguration(configuration);
copied to clipboard
注意：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');
}
});
copied to clipboard
开启断点续传
注意： 断点续传功能的开启时机，必须要在初始化 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);
copied to clipboard
错误码说明



错误码
说明
解决方法




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