Simple Log Service:Get started with Simple Log Service SDK for Flutter

Prerequisites

Simple Log Service SDK for Flutter is installed. For more information, see Install Simple Log Service SDK for Flutter.

Initialize the SDK

In common scenarios, you can initialize the SDK based on the following code. If you want to specify the size of each log packet that needs to be sent to Simple Log Service and enable the resumable upload feature, you can configure the LogProducerConfiguration class. For more information, see Configure the parameters in the LogProducerConfiguration class.

import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

AliyunLogDartSdk? _aliyunLogSdk;

void _initProducer() async {
  // Specify the Simple Log Service endpoint, project name, and Logstore name. You can dynamically configure the parameters. 
    LogProducerConfiguration configuration = LogProducerConfiguration(
      endpoint: 'your endpoint', project: 'your project', logstore: 'your logstore'
    ); 
  // The AccessKey pair that is used to access Simple Log Service. For more information, see AccessKey pair. The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in Simple Log Service is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
    configuration.accessKeyId = 'your access key id';
    configuration.accessKeySecret = 'your access key secret';
    configuration.securityToken = 'your access key token'; // Specify the Security Token Service (STS) token. This parameter is required only if you use STS to obtain a temporary AccessKey pair. 
    _aliyunLogSdk = AliyunLogDartSdk();
    LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);
}

For more information about how to obtain the required information for SDK initialization, see the following topics:

• Endpoints

• AccessKey pair

Report logs

You can use the addLog method to report custom business logs.

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': 'Chinese'
});

If code == LogProducerResult.ok is returned, logs are reported. If error codes are returned, you can troubleshoot the errors by following the instructions provided in the Error codes section of this topic.

Obfuscation rules

If obfuscation is enabled for your Flutter project, you must add the following rules to the obfuscation configuration file of the flutter project. Otherwise, Android projects may not run as expected. By default, obfuscation is enabled for Flutter V1.16.2 and later. iOS projects are not affected by the rules.

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

Configure dynamic parameters

Simple Log Service SDK for Flutter supports dynamic configuration of parameters such as Endpoint, Project, Logstore, and AccessKey.

• Sample code that is used to dynamically configure the Endpoint, Project, and Logstore parameters:

  await _aliyunLogSdk!.setEndpoint('new-endpoint');
  await _aliyunLogSdk!.setProject('new-project-name');
  await _aliyunLogSdk!.setLogstore('new-logstore-name');

• Sample code that is used to dynamically configure the AccessKey parameter:

  // The SecurityToken parameter is optional. This parameter is required only if you use STS to obtain a temporary AccessKey pair. 
  await _aliyunLogSdk!.setAccessKey('your accesskey id', 'your accesskey secret', securityToken: 'your accesskey token');

• Sample code that is used to dynamically configure the Source, Topic, and Tag parameters:

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

• Sample code that is used to dynamically configure other parameters:

  Important

  The AliyunLogDartSdk.updateConfiguration() method does not support dynamic configuration of resumable upload-related parameters.

  LogProducerConfiguration configuration = LogProducerConfiguration();
  configuration.dropDelayLog = true;
  configuration.dropUnauthorizedLog = true;
  // You can dynamically configure the parameters in the LogProducerConfiguration class in the same manner. 
  await _aliyunLogSdk!.updateConfiguration(configuration);

Configure callback for log sending

Simple Log Service SDK for Flutter supports callback for log sending. When a log is sent or fails to be sent, callback information is generated. You can use the callback information to view the status of the SDK or update the parameter settings of the SDK.

_aliyunLogSdk!.setLogCallback((resultCode, errorMessage, logBytes, compressedBytes) {
	// A parameter error occurs. You need to update parameter settings. 
	if (LogProducerResult.parametersInvalid == resultCode) {
	// For example, you can modify the Endpoint parameter. 
	_aliyunLogSdk!.setEndpoint('your endpoint');
	// A parametersInvalid error occurs. This is because no AccessKey pair is specified or the specified AccessKey pair is invalid. 
	_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
}

 	// An authorization timeout error occurs. You need to update your AccessKey pair. 
	if (LogProducerResult.sendUnauthorized == resultCode) {
		_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
	}
});

Enable resumable upload

Sample code that is used to enable resumable upload when AliyunLogDartSdk is initialized:

configuration.persistent = true; // Enable resumable upload. 
configuration.persistentFilePath = 'flutter/demo'; // The path to the cache of binary logs. 
configuration.persistentForceFlush = false; // Disable forceful refresh. We recommend that you disable forceful refresh because it deteriorates system performance. 
configuration.persistentMaxFileCount = 10; // The maximum number of files that can be cached. Default value: 10. 
configuration.persistentMaxFileSize = 1024 * 1024; // The maximum size of each cached file. Default value: 1024 * 1024. 
configuration.persistentMaxLogCount = 64 * 1024; // The maximum number of logs that can be cached. Default value: 64 * 1024. 
_aliyunLogSdk = AliyunLogDartSdk();
LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);

Configure the parameters in the LogProducerConfiguration class

The following table describes the parameters that you can configure in the LogProducerConfiguration class.

Error codes