Flutter SDK quick start - Simple Log Service: Central de Documentação do Alibaba Cloud

Colete e envie logs de aplicativos Flutter para o Simple Log Service (SLS) com o SLS Flutter SDK. O SDK é compatível com Android 4.0 ou superior e iOS 10.0 ou superior, e oferece recursos como upload retomável, configuração dinâmica e callbacks de log.

Notas de versão

O SLS Flutter SDK está publicado no repositório oficial de pacotes Dart. Para mais informações, consulte Aliyun Log Flutter Release.

Código de exemplo

Para exemplos completos e funcionais, consulte Aliyun Log Flutter SDK Example.

Pré-requisitos

Instale o ambiente de desenvolvimento Flutter.

O SLS Flutter SDK é compatível com Android 4.0 ou superior e iOS 10.0 ou superior.

Para builds do iOS, adicione as linhas a seguir ao 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'

Procedimento

Etapa 1: Instalar o SDK

Crie um projeto Flutter.
Adicione o módulo do SLS Flutter SDK. Na raiz do projeto, execute o comando:
```
flutter pub add aliyun_log_dart_sdk
```
Após a conclusão do processo, as informações abaixo são adicionadas automaticamente ao arquivo pubspec.yaml do projeto e o comando flutter pub get é executado implicitamente.
```
dependencies:
 aliyun_log_dart_sdk: ^1.0.0 // For more version information, see the Flutter SDK overview.
```

Importe o pacote no arquivo Dart.

import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

Etapa 2: Inicializar o SDK

O código a seguir demonstra uma inicialização básica. Para opções avançadas de configuração, como tamanho do pacote de logs e upload retomável, consulte Parâmetros de configuração.

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);
}

Etapa 3: Enviar logs

Chame o método addLog para enviar logs personalizados do aplicativo:

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

Os logs são enviados com sucesso apenas se code == LogProducerResult.ok. Caso contrário, um código de erro é retornado. Para mais detalhes, consulte Códigos de erro.

Etapa 4: Configurar regras de ofuscação (Android)

Se o projeto Flutter tiver regras de ofuscação ativadas (habilitadas por padrão no Flutter v1.16.2 e posteriores), adicione também as regras abaixo ao arquivo de configuração de ofuscação do projeto. Sem essa alteração, o projeto Android pode não ser executado corretamente. Projetos iOS não são afetados por esta regra.

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

Configuração dinâmica

Atualize os seguintes parâmetros em tempo de execução: Endpoint, Project, Logstore e AccessKey.

Atualize o Endpoint, o Project e o Logstore.

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

Atualize o 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');

Atualize os parâmetros source, topic e tag.

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

Atualize outros parâmetros.

Importante

O método AliyunLogDartSdk.updateConfiguration() não permite atualizar parâmetros de upload retomável em tempo de execução.

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);

Definir um callback de log

Configure um callback para as operações de envio de logs. Esse callback é acionado tanto em caso de sucesso quanto de falha, o que permite monitorar o status do SDK e atualizar configurações.

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

Ativar upload retomável

Importante

Para usar o recurso de upload retomável, ative-o durante a inicialização do AliyunLogDartSdk. Não é possível modificar dinamicamente a configuração de upload retomável após a inicialização do SDK.

Configure o upload retomável durante a inicialização:

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);

Parâmetros

A tabela a seguir lista os parâmetros compatíveis com a classe LogProducerConfiguration.

Parâmetro	Tipo	Descrição
endpoint	string	URL da região onde o projeto reside. Exemplo: `cn-hangzhou.log.aliyuncs.com`. Para mais informações, consulte Endpoint.
project	string	Nome do Project. Para mais informações, consulte Project.
logstore	string	Nome do Logstore. Para mais informações, consulte Logstore.
accessKeyId	string	Seu AccessKey ID. Para mais informações, consulte AccessKey pair.
accessKeySecret	string	Seu AccessKey Secret. Para mais informações, consulte AccessKey pair.
securityToken	string	Token de segurança necessário para autenticação via Security Token Service (STS). Para mais informações, consulte AssumeRole.
debuggable	bool	Define se o Modo de Depuração deve ser ativado. Padrão: false. Ative este modo ao solucionar problemas na coleta de logs.
maxBufferLimit	int	Memória máxima que o SDK pode utilizar para cache. Unidade: bytes. Padrão: 64 1024 1024.
connectTimeout	int	Tempo limite de conexão de rede, em segundos. Padrão: 10. Não altere este valor salvo se necessário.
sendTimeout	int	Tempo limite para envio de dados, em segundos. Padrão: 15. Não altere este valor salvo se necessário.
ntpTimeOffset	int	Diferença entre a hora do dispositivo e a hora padrão, em segundos. Padrão: 0. Não altere este valor desnecessariamente, pois o SDK corrige a hora automaticamente.
maxLogDelayTime	int	Diferença máxima permitida entre o timestamp do log e a hora local do dispositivo. Unidade: segundos. Padrão: 7 24 3600. Se esse valor for excedido, o log será processado conforme o parâmetro dropDelayLog. Não altere este valor salvo se necessário.
dropDelayLog	bool	Define a política para lidar com logs que excedem maxLogDelayTime. O valor padrão é false, o que significa que os logs não são descartados. O campo `__time__` é redefinido para a hora atual.
dropUnauthorizedLog	bool	Define se logs com falha na autenticação devem ser descartados. Padrão: false.
source	string	Campo `__source__` , que indica a origem do log. Padrão: Android ou iOS.
topic	string	Campo `__topic__` , que indica o Tópico do Log. Sem valor padrão.
Tags (via método addTag())	string	Valor do campo `__tag__:xxx:yyy` , que representa os metadados da tag. Este campo não possui valor padrão. Defina o valor chamando o método `LogProducerConfiguration.addTag()` ou `AliyunLogDartSdk.addTag()`. .
packetLogBytes	int	Tamanho de cada pacote de logs a ser enviado. Valores válidos: 1 a 5.242.880. Unidade: bytes. Padrão: 1024 * 1024.
packetLogCount	int	Número máximo de logs em cada pacote. Valores válidos: 1 a 4.096. Padrão: 1.024.
packetTimeout	int	Tempo limite para um pacote de logs. Ao atingir o tempo limite, o pacote é enviado imediatamente. Unidade: milissegundos. Padrão: 3000.
persistent	boolean	Define se o recurso de upload retomável deve ser ativado. Padrão: false. Ative este recurso para evitar perda de dados.
persistentForceFlush	boolean	Define se o cache deve ser forçado a cada chamada do addLog. `true`: Ativado. A ativação pode afetar o desempenho. `false` (Padrão): Desativado. Ative este recurso apenas em cenários de alta confiabilidade.
persistentFilePath	string	Caminho para armazenar binlogs em cache para upload retomável. Padrão: string vazia. Importante O caminho especificado deve existir. Cada instância de `AliyunLogDartSdk` requer um caminho exclusivo.
persistentMaxFileCount	int	Número máximo de arquivos persistentes. Padrão: 10.
persistentMaxFileSize	int	Tamanho máximo de cada arquivo persistente, em bytes. Padrão: 1024*1024.
persistentMaxLogCount	int	Número máximo de logs que podem ser armazenados em cache. Padrão: 64*1024.

Códigos de erro

Código de erro	Descrição	Solução
invalid	O SDK não foi inicializado ou foi destruído.	Verifique se o SDK foi inicializado corretamente e se o método `destroy()` não foi chamado.
writeError	Ocorreu um erro de gravação, provavelmente porque a cota de tráfego de escrita do Project foi excedida.	Ajuste a cota de tráfego de escrita do Project. Para mais informações, consulte Ajustar cotas de recursos.
dropError	O cache está cheio.	Consulte as descrições dos parâmetros da classe `LogProducerConfiguration`, ajuste os valores dos parâmetros maxBufferLimit, persistentMaxLogCount e persistentMaxFileSize e tente novamente.
sendNetworkError	Erro de rede.	Verifique sua conexão de rede e tente novamente.
sendQuotaError	O tráfego de escrita do Project atingiu o limite.	Ajuste a cota de tráfego de escrita do Project. Para mais informações, consulte Ajustar cotas de recursos.
sendUnauthorized	O AccessKey expirou, é inválido ou sua política de permissões está incorreta.	Verifique se o seu AccessKey é válido e se o usuário RAM associado tem as permissões necessárias nos recursos do SLS. Para mais informações, consulte Conceder permissões a um usuário RAM.
sendServerError	Erro no servidor.	Tente novamente.
sendDiscardError	Os dados foram descartados. Isso geralmente ocorre devido a discrepância de horário entre o dispositivo e o servidor.	O SDK reenvia os dados automaticamente. Nenhuma ação é necessária.
sendTimeError	A hora do dispositivo não está sincronizada com a hora do servidor.	O SDK resolve esse problema automaticamente. Nenhuma ação é necessária.
sendExitBuffered	Dados em cache não foram enviados antes da destruição do SDK.	Ative o upload retomável para evitar perda de dados.
parametersInvalid	Parâmetros de inicialização do SDK inválidos.	Verifique as configurações de AccessKey, Endpoint, Project e Logstore.
persistentError	Falha ao gravar dados em cache no disco.	Verifique se o caminho do arquivo de cache está configurado corretamente, se o cache não está cheio e se há espaço suficiente em disco.
unknown	Erro desconhecido.	Tente novamente.