文档

Flutter SDK快速入门

更新时间:

本文介绍如何快速使用日志服务Flutter SDK采集日志数据。

前提条件

已安装日志服务Flutter SDK。具体操作,请参见安装Flutter SDK

初始化SDK

一般场景下,您可以参考以下代码进行初始化。若您需要配置LogProducerConfiguration类,例如配置详细的上传日志包大小、开启断点续传功能等。详细配置说明,请参见配置参数说明

import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

AliyunLogDartSdk? _aliyunLogSdk;

void _initProducer() async {
  // 配置服务入口Endpoint、Project名称、Logstore名称。您可以通过动态参数配置动态更新Endpoint、Project名称等。
    LogProducerConfiguration configuration = LogProducerConfiguration(
      endpoint: 'your endpoint', project: 'your project', logstore: 'your logstore'
    ); 
  //阿里云访问密钥AccessKey。更多信息,请参见访问密钥。阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维。
    configuration.accessKeyId = 'your access key id';
    configuration.accessKeySecret = 'your access key secret';
    configuration.securityToken = 'your access key token'; // 仅当您使用令牌服务(STS)方式获取临时AccessKey时需要配置。
    _aliyunLogSdk = AliyunLogDartSdk();
    LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);
}

您可以参考以下文档获取SDK初始化所需的Endpoint、AccessKey等。

上报日志

可以通过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时才表示上报日志成功。其他情况下返回错误码,请参见错误码说明

混淆规则

如果您的flutter项目开启了混淆规则(Flutter 1.16.2及以版本默认开启混淆规则),您还需要在您项目的混淆配置文件中加入以下规则,否则Android项目可能无法正常运行。iOS项目不受此规则影响。

-keep class com.aliyun.sls.android.producer.* { *; }
-keep interface com.aliyun.sls.android.producer.* { *; }

动态化配置参数

日志服务Flutter SDK支持动态化配置Endpoint、Project、Logstore、AccessKey等参数。

  • 动态化配置Endpoint、Project、Logstore参数。

    await _aliyunLogSdk!.setEndpoint('new-endpoint');
    await _aliyunLogSdk!.setProject('new-project-name');
    await _aliyunLogSdk!.setLogstore('new-logstore-name');
  • 动态化配置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');
  • 动态化配置其他参数

    重要

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

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

设置日志发送回调

日志服务Flutter SDK支持设置日志发送回调。日志发送成功或失败时,都会产生对应的回调信息。您可以通过回调信息来确定SDK的运行情况,或者更新SDK的参数配置。

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

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

开启断点续传

重要

如果要开启断点续传功能,您必须要在初始化AliyunLogDartSdk时开启。SDK初始化完成后不支持动态修改断点续传相关配置信息。

您可以参考如下代码,在初始化AliyunLogDartSdk时开启断点续传功能。

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

配置参数说明

LogProducerConfiguration类支持的参数配置如下表所示。

参数

数据类型

说明

endpoint

string

Project所在地域的服务入口。例如cn-hangzhou.log.aliyuncs.com。如何获取,请参见服务入口

project

string

Project名称。更多信息,请参见项目(Project)

logstore

string

Logstore名称。更多信息,请参见日志库(Logstore)

accesskeyId

string

用于访问日志服务的AccessKey ID。 如何获取,请参见访问密钥

accessKeySecret

string

用于访问日志服务的AccessKey Secret。 如何获取,请参见访问密钥

securityToken

string

访问日志服务的访问密钥Token。使用令牌服务(STS)方式接入时,需要配置。如何获取,请参见AssumeRole - 获取扮演角色的临时身份凭证

debuggable

bool

是否开启调试模式。默认为false,表示关闭。

当遇到数据采集问题时建议开启。

maxBufferLimit

int

最大可用内存上限。默认为64*1024*1024,单位为Byte。

connectTimeout

int

网络连接超时时间。默认为10秒。一般不建议修改。

sendTimeout

int

网络发送超时时间。默认为15秒。一般不建议修改。

ntpTimeOffset

int

设备时间与标准时间之差。默认为0秒。不建议修改,SDK已经支持时间自动校正。

maxLogDelayTime

int

日志时间与本机时间之差。默认为7天。超过该值后,会根据 dropDelayLog参数进行处理。不建议修改。

dropDelayLog

bool

对超过maxLogDelayTime的日志的处理策略。默认为false,不丢弃。__time__

会重置为当前时间。

dropUnauthorizedLog

bool

是否丢弃鉴权失败的日志。默认为false,不丢弃。

source

string

__source__

字段的值,即日志源。默认为Android、iOS。

topic

string

__topic__

字段的值,即日志主题。无默认值。

_tags

string

__tag__:xxx:yyy

字段的值,即标签元数据信息。无默认值。需要通过LogProducerConfiguration.addTag()AliyunLogDartSdk.addTag()

方法设置。

packetLogBytes

int

每个待发送日志包的大小。取值为1~5242880,单位为字节。默认为1024 * 1024。

packetLogCount

int

每个待发送日志包中日志数量的最大值。取值为1~4096,默认为1024。

packetTimeout

int

待发送日志包等待超时时间,超时则会立即发送。单位为毫秒,默认为3000。

persistent

boolean

是否开启断点续传功能。默认为false。建议开启。

persistentForceFlush

boolean

是否开启每次AddLog强制刷新功能。

true:开启。开启后对性能会有影响,建议谨慎开启。

false(默认值):关闭。

在高可靠性场景下建议开启。

persistentFilePath

string

断点续传binlog缓存路径。默认为空字符串。

重要

配置的路径必须存在,且不同 AliyunLogDartSdk实例对应的路径必须不同。

persistentMaxFileCount

int

持久化文件个数。默认为10。

persistentMaxFileSize

int

每个持久化文件大小。默认为1024*1024。

persistentMaxLogCount

int

最多缓存的日志数量。默认为64*1024。

错误码说明

错误码

说明

解决方法

invalid

SDK已销毁或无效。

  1. 检查是否正确初始化SDK。

  2. 检查是否调用了destroy()方法。

writeError

数据写入错误,可能原因是Project写入流量已达上限。

调整Project写入流量上限。具体操作,请参见调整资源配额

dropError

缓存已满。

参考配置LogProducerConfiguration类参数说明部分,调整maxBufferLimit、persistentMaxLogCount、persistentMaxFileSize参数值后重试。

sendNetworkError

网络错误。

请检查网络连接情况后重试。

sendQuotaError

Project写入流量已达上限。

调整Project写入流量上限。具体操作,请参见调整资源配额

sendUnauthorized

AccessKey过期、无效或AccessKey权限策略配置不正确。

检查AccessKey。

RAM用户需具备操作日志服务资源的权限。具体操作,请参见为RAM用户授权

sendServerError

服务错误,

提请工单联系技术支持。

sendDiscardError

数据被丢弃,一般是设备时间与服务器时间不同步导致

SDK会自动重新发送。

sendTimeError

设备时间与服务器时间不同步。

SDK会自动修复该问题。

sendExitBuffered

SDK销毁时,缓存数据还没有上报。

建议开启断点续传功能可避免数据丢失。

parametersInvalid

SDK初始化参数错误。

检查AccessKey、Endpoint、Project、Logstore等参数配置。

persistentError

缓存数据写入磁盘失败。

  1. 检查缓存文件路径配置是否正确。

  2. 检查缓存文件是否写满

  3. 检查系统磁盘空间是否充足。

unknown

未知错误

建议重试。若无法解决,请提工单申请联系技术支持。

  • 本页导读 (1)
文档反馈