Simple Log Service：Android SDK快速入門

動態配置參數

Android SDK支援動態化設定Endpoint、ProjectName、Logstore、AccessKey等參數。

• 動態化配置Endpoint、ProjectName、Logstore。

  // 支援獨立配置或一起配置Endpoint、ProjectName、Logstore等參數。
  // 更新Endpoint。
  config.setEndpoint("your new-endpoint");
  // 更新Project名稱。
  config.setProject("your new-project");
  // 更新Logstore名稱。
  config.setLogstore("your new-logstore");

• 動態化配置AccessKey。

  動態化配置AccessKey時，一般建議與LogProducerCallback結合使用。

  // 如果您在初始化LogProducerClient時已經完成了LogProducerCallback的初始化，以下代碼可忽略。
  final LogProducerCallback callback = new LogProducerCallback() {
      @Override
      public void onCall(int resultCode, String reqId, String errorMessage, int logBytes, int compressedBytes) {
          // resultCode: 狀態代碼。更多資訊，請參見錯誤碼。
          // reqId: 請求ID, 已廢棄。
          // errorMessage: 失敗資訊。
          // logBytes: 日誌原始位元組數。
          // compressedBytes: 日誌壓縮位元組數。
  
          final LogProducerResult result = LogProducerResult.fromInt(resultCode);
          if (LogProducerResult.LOG_PRODUCER_SEND_UNAUTHORIZED == result || LogProducerResult.LOG_PRODUCER_PARAMETERS_INVALID == result) {
              // 需要更新AccessKey或者SDK的初始化參數。
              requestAccessKey();
          }
      }
  };
  
  // 需要關注日誌的發送成功或失敗狀態時, 第二個參數需要傳入一個callback。
  client = new LogProducerClient(config, callback);
  
  // 請求AccessKey資訊。
  private void requestAccessKey() {
      // 推薦您先使用移動端日誌直傳服務配置AccessKey資訊。
      // ...
  
      // 擷取AccessKey資訊後，完成更新。
      updateAccessKey(accessKeyId, accessKeySecret, securityToken);
  }
  
  // 更新AccessKey資訊。
  private void updateAccessKey(String accessKeyId, String accessKeySecret, String securityToken) {
      // 通過STS服務擷取的AccessKey包含securityToken，需要使用以下方式更新。
      if (null != securityToken && !"".equals(securityToken)) {
          config.resetSecurityToken(accessKeyId, accessKeySecret, securityToken);
      } else {
          // 不是通過STS服務擷取的AccessKey，使用以下方式更新。
          config.setAccessKeyId(accessKeyId);
          config.setAccessKeySecret(accessKeySecret);
      }
  }

• 動態化配置source、topic、tag。

  重要

  source、topic、tag無法針對某類日誌進行設定。一旦設定後，所有未成功發送到Log Service的日誌，都可能會更新。如果您需要通過source、topic、tag來跟蹤具體類別的日誌，可能會導致與您的業務預期不相符合。建議您在產生Log時新增欄位來標識對應的類別資訊。

  // 設定日誌來源。
  config.setSource("your new-source");
  // 設定日誌主題。
  config.setTopic("your new-topic");
  // 設定tag資訊，此tag資訊將被附加在每條日誌上。
  config.addTag("test", "your new-tag");

斷點續傳

Android SDK支援斷點續傳。開啟斷點續傳後，每次通過addLog方法寫入成功的日誌都會先儲存在本地binlog檔案中，確認日誌發送成功後才會刪除本機資料，確保日誌上傳實現At Least Once。

您可以在SDK初始化時加入以下代碼，實現斷點續傳。

private void initProducer() {
    // 1表示開啟斷點續傳功能，0表示關閉。預設值為0。
    config.setPersistent(1);
    // 持久化的檔案名稱，需要保證檔案所在的檔案夾已建立。
    final String persistentFilePath = getFilesDir() + File.separator + "log_data";
    config.setPersistentFilePath(persistentFilePath);
    // 持久化檔案滾動個數，建議設定為10。
    config.setPersistentMaxFileCount(10);
    // 每個持久化檔案的大小，單位為Byte，格式為N*1024*1024。建議N的取值範圍為1~10。
    config.setPersistentMaxFileSize(N*1024*1024);
    // 本地最多緩衝的日誌數量，不建議超過1048576，預設為65536。
    config.setPersistentMaxLogCount(65536);
}

混淆規則

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

Android許可權

<uses-permission android:name="android.permission.INTERNET" />

為什麼會存在重複日誌？

Android SDK發送日誌的過程是非同步，受網路狀態影響，日誌可能會發送失敗並重新發送。由於SDK只在介面返回200狀態代碼時才認為發送成功，因此日誌會存在一定的重複率。建議您通過SQL查詢分析語句對日誌進行去重。

如果日誌重複率較高，您需要先排查下SDK初始化是否存在問題。主要原因和解決方案如下：

• 斷點續傳配置錯誤

  針對斷點續傳配置錯誤，您需要確認setPersistentFilePath方法傳入的檔案路徑是否全域唯一。

• SDK重複初始化

  • 造成SDK重複初始化的常見原因是單個執行個體寫法錯誤，或者沒有使用單例模式封裝SDK的初始化，建議您參考以下方式完成SDK初始化。

    public class AliyunLogHelper {
        private LogProducerConfig config;
        private LogProducerClient client;
    
        private static class Holder {
            private static final AliyunLogHelper INSTANCE = new AliyunLogHelper();
        }
    
        public static AliyunLogHelper getInstance() {
            return Holder.INSTANCE;
        }
    
        private AliyunLogHelper() {
            initProducer();
        }
    
        private void initProducer() {
            // 以下代碼替換為您的初始化代碼。
            try {
                config = new LogProducerConfig();
                client = new LogProducerClient(config);
            } catch (LogProducerException e) {
                e.printStackTrace();
            }
        }
    
        public void addLog(Log log) {
            if (null == client) {
                return;
            }
    
            client.addLog(log);
        }
    }

  • 另外一個造成SDK重複初始化的原因是多進程。建議您只在主進程初始化SDK，或者在不同進程中初始化SDK時，設定setPersistentFilePath為不同的值，確保唯一性。

• 弱網環境配置最佳化

  如果您的應用是在弱網環境下使用，建議您參考如下樣本最佳化SDK配置參數。

  // 初始化SDK。
  private void initProducer() {
      // 調整HTTP連結和發送逾時時間，有利於減少日誌重複率。
      // 您可以根據實際情況調整具體的逾時時間。
      config.setConnectTimeoutSec(20);
      config.setSendTimeoutSec(20);
    
      // 其他初始化參數。
      // ...
  }

日誌缺失，如何處理？

日誌上報的過程是非同步，如果在上報日誌前App被關閉，則日誌有可能無法被上報，造成日誌丟失。建議您開啟斷點續傳功能，具體操作，請參見斷點續傳。

日誌上報延時，如何處理？

SDK發送日誌的過程是非同步，受網路環境以及應用使用情境的影響，日誌可能不會立即上報。如果只有個別裝置出現日誌上報延時，這種情況是正常的，否則請您根據如下錯誤碼進行排查。

Android SDK是否支援DNS預解析和緩衝策略？

以下提供Android SDK結合HTTPDNS SDK以及OkHttp實現DNS預解析和緩衝策略的樣本。

1. 實現自訂 DNS 介面。

   /**
     * 基於OkHttp Dns 介面，實現自訂 Dns 解析服務，供參考。
     */
   public class OkHttpDns implements Dns {
     private Context mContext;
   
     public OkHttpDns(Context context) {
       mContext = context;
     }
   
     @Override
     public List<InetAddress> lookup(String host) throws UnknownHostException {
       // !!注意!! 
       // accountId 需要替換為您在HTTPDNS服務申請的值，具體請參考HTTPDNS文檔
       HTTPDNSResult httpdnsResult = HttpDns.getService(mContext, accountId)
         .getHttpDnsResultForHostSync(host, RequestIpType.both);
       List<InetAddress> inetAddresses = new ArrayList<>();
       InetAddress address;
       try {
         if (httpdnsResult.getIps() != null) {
           //處理IPv4地址
           for (String ipv4 : httpdnsResult.getIps()) {
             address = InetAddress.getByName(ipv4);
             inetAddresses.add(address);
           }
         }
   
         if (httpdnsResult.getIpv6s() != null) {
           //處理IPv6地址
           for (String ipv6 : httpdnsResult.getIpv6s()) {
             address = InetAddress.getByName(ipv6);
             inetAddresses.add(address);
           }
         }
       } catch (UnknownHostException e) {
   
       }
   
       if (!inetAddresses.isEmpty()) {
         return inetAddresses;
       }
   
       return okhttp3.Dns.SYSTEM.lookup(host);
     }
   }

2. 實現自訂NetworkInterface。

   /**
      * 基於 OkHttp 實現 SLS SDK 的 NetworkInterface，供參考
      */
   private static class OkHttpNetworkInterface implements LogProducerHttpTool.NetworkInterface {
   
     private OkHttpClient client;
   
     public OkHttpNetworkInterface(Context context) {
       client = new OkHttpClient.Builder()
         .connectTimeout(30, TimeUnit.SECONDS)
         .readTimeout(30, TimeUnit.SECONDS)
         .writeTimeout(30, TimeUnit.SECONDS)
         .dns(new OkHttpDns(context))
         .build();
     }
   
     @Override
     public NetworkResponse send(String urlString, String method, String[] header, byte[] body) {
       // 建議先調用一次SDK原始的實現，在日誌上報失敗時再通過OkHttp上報。
       LogHttpResponse logHttpResponse = LogProducerHttpTool.android_http_post(urlString, method, header, body);
       if (logHttpResponse.getStatusCode() != -1) {
         NetworkResponse response = new NetworkResponse();
         response.statusCode = logHttpResponse.getStatusCode();
         response.errorMessage = logHttpResponse.getErrorMessage();
         return response;
       }
   
       // 通過 OkHttp 上報日誌
       Request.Builder builder = new Request.Builder();
       builder.url(urlString);
       builder.post(RequestBody.create(body));
   
       for (int i = 0; i < header.length; i += 2) {
         builder.addHeader(header[i], header[i + 1]);
       }
   
       // 不管請求成功或失敗，都需要返回 NetworkResponse，否則SDK的運行可能會出錯
       try (okhttp3.Response response = client.newCall(builder.build()).execute()) {
         NetworkResponse httpResponse = new NetworkResponse();
         httpResponse.statusCode = response.code();
         httpResponse.headers = response.headers().toMultimap();
         httpResponse.errorMessage = response.message();
   
         return httpResponse;
       } catch (IOException e) {
         NetworkResponse httpResponse = new NetworkResponse();
         httpResponse.statusCode = -1;
         httpResponse.headers = null;
         httpResponse.errorMessage = e.getLocalizedMessage();
   
         return httpResponse;
       }
     }
   
   }
   

3. 完成SLS SDK初始化。

   public class AliyunSLS {
     private void initSLS(Context context) {
       // 給SLS SDK設定自訂 NetworkInterface
       // !!!注意!!!
       // 該設定會對所有SLS SDK的樣本生效
       LogProducerHttpTool.setNetworkInterface(new OkHttpNetworkInterface(context));
   
       // 初始化SLS SDK
       initProducer();
     }
   
     private void initProducer() {
       // 這裡正常實現 LogProducerConfig 和 LogProducerClient 的初始化。
       // ...
     }
   }