Simple Log Service:Flutter SDK quickstart

Release notes

The SLS Flutter SDK is published on the official Dart package repository. For more information, see Aliyun Log Flutter Release.

Sample code

For complete working examples, see Aliyun Log Flutter SDK Example.

Prerequisites

• Install the Flutter development environment.

• The SLS Flutter SDK supports Android 4.0 or later and iOS 10.0 or later.

  • For iOS builds, you must add the following to your Podfile:

    source 'https://github.com/CocoaPods/Specs.git'
    source 'https://github.com/aliyun-sls/Specs.git'
    # If you are using a repository in Chinese mainland, you must also add this line.
    source 'https://gitee.com/aliyun-sls/Specs.git'

Procedure

Step 1: Install the SDK

1. Create a Flutter project.

2. Add the SLS Flutter SDK module. From the root of your project, run the following command:

   flutter pub add aliyun_log_dart_sdk

   After the process is complete, the following information is automatically added to the project's pubspec.yaml file, and flutter pub get is implicitly run.

   dependencies:
    aliyun_log_dart_sdk: ^1.0.0 // For more version information, see the Flutter SDK overview.

3. Import the package in your Dart file.

   import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

Step 2: Initialize the SDK

The following code demonstrates basic initialization. For advanced configuration options such as log package size and resumable upload, see Configuration parameters.

import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

AliyunLogDartSdk? _aliyunLogSdk;

void _initProducer() async {
  // Set the endpoint, project name, and Logstore name.
    LogProducerConfiguration configuration = LogProducerConfiguration(
      endpoint: 'your endpoint', project: 'your project', logstore: 'your logstore'
    ); 
  // An Alibaba Cloud AccessKey. Using an AccessKey pair is risky as it grants full access to your resources. We strongly recommend using a RAM User for API calls.
    configuration.accessKeyId = 'your access key id';
    configuration.accessKeySecret = 'your access key secret';
    configuration.securityToken = 'your access key token'; // Required only when using a temporary AccessKey from Security Token Service (STS).
    _aliyunLogSdk = AliyunLogDartSdk();
    LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);
}

Step 3: Send logs

Call the addLog method to send 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 content'
});

Logs are sent successfully only if code == LogProducerResult.ok. Otherwise, an error code is returned. For more information, see Error codes.

Step 4: Configure obfuscation rules (Android)

If your Flutter project has obfuscation rules enabled (these rules are enabled by default in Flutter v1.16.2 and later), you also need to add the following rules to your project's obfuscation configuration file. Otherwise, the Android project may not run correctly. iOS projects are not affected by this rule.

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

Dynamic configuration

The following parameters can be updated at runtime: Endpoint, Project, Logstore, and AccessKey.

• Update the Endpoint, Project, and Logstore.

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

• Update the AccessKey.

  // The securityToken is optional. It is required only when the AccessKey is obtained through Security Token Service (STS).
  await _aliyunLogSdk!.setAccessKey('your accesskey id', 'your accesskey secret', securityToken: 'your accesskey token');

• Update source, topic, and tag parameters.

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

• Update other parameters.

  Important

  AliyunLogDartSdk.updateConfiguration() does not support updating resumable upload parameters at runtime.

  LogProducerConfiguration configuration = LogProducerConfiguration();
  configuration.dropDelayLog = true;
  configuration.dropUnauthorizedLog = true;
  // Other parameters of the LogProducerConfiguration class can also be set this way.
  await _aliyunLogSdk!.updateConfiguration(configuration);

Set a log callback

Set a callback for log-sending operations. The callback triggers on both success and failure, enabling SDK status monitoring and configuration updates.

_aliyunLogSdk!.setLogCallback((resultCode, errorMessage, logBytes, compressedBytes) {
	// The parameters are invalid. You need to update the configuration.
	if (LogProducerResult.parametersInvalid == resultCode) {
	// For example, update the Endpoint.
	_aliyunLogSdk!.setEndpoint('your endpoint');
	// A missing or incorrect AccessKey also triggers parametersInvalid.
	_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
}

 	// The authorization has expired. You need to update the AccessKey.
	if (LogProducerResult.sendUnauthorized == resultCode) {
		_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
	}
});

Enable resumable upload

Configure resumable upload during initialization:

configuration.persistent = true; // Enable resumable upload.
configuration.persistentFilePath = 'flutter/demo'; // The directory to cache binlogs.
configuration.persistentForceFlush = false; // Disable force flush. Keep this disabled, as enabling it can affect performance.
configuration.persistentMaxFileCount = 10; // The maximum number of cached files. Default: 10.
configuration.persistentMaxFileSize = 1024 * 1024; // The maximum size of a single cache file, in bytes. Default: 1024 * 1024.
configuration.persistentMaxLogCount = 64 * 1024; // The maximum number of cached logs. Default: 64 * 1024.
_aliyunLogSdk = AliyunLogDartSdk();
LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);

Parameters

The parameters supported by the LogProducerConfiguration class are listed in the following table.

Error codes