日誌服務 HarmonyOS NEXT 日誌採集最佳實踐

作者：高玉龍（元泊）

背景信息

隨着數字化新時代的全面展開以及 5G 與物聯網（IoT）技術的迅速普及，操作系統正面臨前所未有的變革需求。在這個背景下，華爲公司自主研發的鴻蒙操作系統（HarmonyOS）應運而生，旨在滿足萬物互聯時代的多元化設備接入、高效協同和安全可靠運行的需求。

HarmonyOS 不僅着眼於智能手機市場，更是全球首個面向全場景智能生態的操作系統，支持從手機、平板電腦到智能家居、穿戴設備乃至工業控制等多種終端形態。2024 年 1 月 18 日正式推出 HarmonyOS NEXT 鴻蒙星河開發者預覽，深圳市於 2024 年 3 月 3 日也發佈了支持開源鴻蒙原生應用發展的 2024 年行動計劃。

日誌服務（SLS）介紹

日誌服務（SLS，後文簡稱 SLS）是雲原生觀測與分析平臺，爲 Log、Metric、Trace 等數據提供大規模、低成本、實時的平臺化服務。SLS 一站式提供數據採集、加工、查詢與分析、可視化、告警、消費與投遞等功能，全面提升您在研發、運維、運營、安全等場景的數字化能力。

在構建複雜而龐大的應用和智能生態系統過程中，SLS 作爲開發調試、性能優化、運維監控和故障排查的重要基礎設施。爲確保各類應用程序能夠在鴻蒙操作系統上實現無縫對接並高效利用 SLS，對 SLS SDK 進行 HarmonyOS 原生適配成爲必然之舉。

此舉不僅可以提升鴻蒙生態下應用的穩定性和可靠性，也有助於開發者更好地遵循統一的標準和最佳實踐，進一步促進鴻蒙操作系統生態的繁榮與發展。在這種情況下，基於 SLS 的移動應用日誌管理和分析將成爲不可或缺的工具，基於對 SLS+ 移動應用日誌可以幫助開發人員快速定位和解決問題，優化應用性能。

SDK 特性介紹

HarmonyOS 下的 SLS SDK 基於共同的基座 C Core SDK 適配，底層適配鴻蒙NDK。C Core 部分使用純 C 語言編寫，對性能進行了極端優化（包括緩存管理、文件管理、PB 序列化等），能夠適用於 IoT、移動端、服務端等各種場景。SDK 提供 ArkTS 語言原生調用 API。SDK 具備以下特性：

異步
- 客戶端線程寫入無阻塞
- 日誌隊列異步發送
聚合&壓縮上傳
- 日誌聚合發送（支持按超時時間、日誌數、日誌大小聚合）
- 支持 lz4、zstd 壓縮
多實例
- 支持創建多個實例分別發送到不同的目標
- 可以實例配置獨立，互不影響
緩存
- 支持設置可允許佔用的緩存內存上限
- 超過內存緩存上限時，日誌寫入會失敗
自定義標識
- 支持設置自定義 Tag 和 Topic
斷點續傳
- 支持日誌緩存到本地文件，只有發送成功纔會刪除，確保日誌上傳 At Least Once
日誌上下文
- 支持查看某條日誌的上下文，可以更好的定位問題

HarmonyOS SDK 通過 OpenHarmony 三方庫中心託管發佈，當前支持 HarmonyOS NEXT API 9.0 及以上，僅支持 stage 模式。

SDK 使用最佳實踐

準備工作

在使用 HarmonyOS SDK 進行日誌採集之前，您需要做一些準備工作。

已開通日誌服務（SLS），請參見開通日誌服務 [ 1] 。
已創建好對應的 Project 和 Logstore，請參見管理 Project [ 2] 和管理 Logstore [ 3] 。
已創建並獲取 AccessKey，請參見訪問密鑰 [ 4] 。阿里雲賬號 AccessKey 擁有所有 API 的訪問權限，風險很高。強烈建議您創建並使用 RAM 用戶進行 API 訪問或日常運維。RAM 用戶需具備操作日誌服務（SLS）資源的權限。具體操作，請參見爲 RAM 用戶授權 [ 5] 。
[可選]搭建 HarmonyOS 開發環境。開發鴻蒙應用需要使用 HarmonyOS 的 IDE 進行開發，具體內容請參考 HarmonyOS 官網開發文檔 [ 6] 。

日誌採集

安裝 SDK

在項目的 entry 或 library 目錄下執行如下命令。

ohpm install @aliyunsls/producer --registry=https://ohpm.openharmony.cn/ohpm

以上命令執行完成後，在 entry 或 library 目錄下的 oh-package.json5 文件中會自動增加以下信息。

"dependencies": {
 "@aliyunsls/producer": "^0.1.0"
}

你可以通過以上信息來確定 SDK 是否安裝成功。

集成 SDK

SDK 安裝成功後，您可以按照實際業務需要，在指定的 ets 文件中導入 SLS 模塊。

import { AliyunLog } from "@aliyunsls/producer"

您還需要完成 SDK 的初始化工作。

let aliyunLog: AliyunLog = new AliyunLog(
  "https://cn-qingdao.log.aliyuncs.com", // 需要根據實際業務需要，替換爲您Project所在Region
  "test-project-yuanbo", // 需要根據實際業務需要，替換爲您的Project
  "applog", // 需要根據實際業務需要，替換爲您的Logstore
  "<accesskey id>",
  "<accesskey secret>",
  "<accesskey token>" // 僅當AccessKey是通過STS方式獲取時才需要
);

參數說明：

參數名稱	說明
endpoint	SLS 所在地域的訪問域名，請參見服務入口 [ 7] 。
project	SLS 的資源管理單元，請參見項目（Project） [ 8] 。
logstore	SLS 中日誌數據的採集、存儲和查詢單元，請參見日誌庫（Logstore） [ 9] 。
accesskey	調用 API 訪問雲資源的安全口令，請參見訪問密鑰 [ 10] 。

日誌採集

完成 SDK 的初始化之後，可以通過以下方式完成日誌的採集。

aliyunLog.addLog(new Map(
  [
    // 根據實際業務需要，調整您需要上報的業務字段
    ["from", "Home"],
    ["page", "HomePage"],
  ]
));

更多 SDK 使用相關的信息，建議您參考 SLS 官網文檔 HarmonyOS SDK [1****1] 。

日誌使用

場景一：查詢和可視化分析

數據通過 SDK 採集上來之後，我們可以通過 SLS 控制檯進行日誌的查詢和分析。

首先在 SLS 控制檯 Project 列表中找到您的 Project，並進入到 Project 頁面。如下：

接着，在左側日誌庫菜單中找到您的 Logstore。如下：

如果 Logstore 沒有開啓索引，在您打開 Logstore 頁面之後，會收到一個“未開啓日誌庫索引”的提示框。您可以通過 Logstore 頁面右上角的開啓索引按鈕來配置相關字段的索引。配置索引的具體方式可以參考創建索引 [ 12] 這篇文檔。本文示例的 Logstore 已經對以下字段進行了索引配置：

索引開啓後，即可在 Logstore 頁面看到我們上報的日誌信息，如下：

注意： 如果您的日誌是在開啓索引之前寫入的，您需要重建索引後才能看到歷史寫入的數據。如何重建索引？您可以參考文檔重建索引 [ 13] 。

可視化分析示例一：分析 CartPage 的訪問趨勢

基於示例數據，我們可以通過 SQL 查詢出 page 字段的訪問趨勢，如下：

* and page: CartPage | select date_trunc('minute', __time__)  as minute, count(*) as cnt group by minute order by minute asc

以上查詢分析語句的含義是：

“|”之前的部分，是通過查詢語句 page: CartPage 過濾出 page 爲 CartPage 的頁面數據。請參考更多關於查詢語法 [ 14] 的信息。
“|”之後的部分，是通過 SQL 語句對過濾出來的數據進行分析，即：通過 date_trunc 語句把時間對齊到分鐘級別，然後使用 count(*) 計算出每分鐘頁面的訪問次數。請參考更多關於分析語法 [ 15] 的信息。

通過 SLS 可視化能力，可以對查詢分析的結果使用豐富的圖表展示，如下圖是通過“線圖 Pro”類型的圖表，按照時間升序展示每分鐘的頁面訪問次數。

可視化分析示例二：分析 CartPage 頁面的訪問來源

基於示例數據，可以使用如下查詢分析語句查詢 Cart 頁面的來源分佈：

* and page: CartPage | select "from"  as "from", count(*) as cnt group by "from"

備註： 因爲 from 是 SQL 的保留字段，因此示例中使用了雙引號""對 from 進行包裝。

下圖是通過餅圖 Pro 類型的圖表，繪製的來源頁面分佈。

SLS 擁有非常強大的可視化分析能力，以上僅是非常簡單的示例。實際使用中，可能會涉及到多種指標的同比/環比，漏斗轉化實時分析等等。SLS 對此提供了非常靈活和豐富的能力進行支持。更多信息可以參考查詢與分析 [ 16] 以及可視化 [ 17] 。

場景二：日誌加工處理

如果從鴻蒙設備上採集到的原始數據格式沒有事先約定好，或者數據格式較爲複雜，或者需要對個別字段做富化/脫敏等，您可以使用 SLS 數據加工能力對原始數據做富化和清洗。您可以參考以下步驟。

[可選]新增一個 Logstore 用於存儲加工處理後的數據，如下：

可根據實際業務的需要，提前對該 Logstore 進行索引等配置。

進入到數據加工配置頁面

您可以通過 Logstore 名稱右側的“數據加工”超鏈接進入到數據加工配置頁面。

配置數據加工任務

如上圖，您可以參考以下步驟配置數據加工任務。

a. 把目標數據加入到測試數據，用於驗證數據加工腳本是否符合預期。

b. 在腳本編輯區域，根據實際業務需要輸入數據加工腳本規則，示例如下：

# 富化__tag__:__client_ip__字段，提取出省、市、經緯度等信息
e_set("x", geo_parse(v("__tag__:__client_ip__")))
e_json("x", prefix="geo_") # 平鋪x節點，並增加geo_前綴

e_drop_fields("x")

# 平鋪content節點
e_json("content")
e_drop_fields("content")

關於數據加工腳本支持的語法，您可以參考數據加工語法 [ 18] 。

c. 腳本編寫完成後，您可以通過右上角“預覽數據”按鈕驗證數據加工的結果。

如下圖，是以上數據加工腳本的預覽結果：

數據加工預覽結果符合預期後，您就可以保存當前數據加工任務了，後續的具體操作請參考創建數據加工任務 [ 19] 。

其他場景

除了上文中提到的查詢與可視化分析、日誌加工處理之外，SLS 還支持基於業務日誌創建自定義告警監控業務，通過流處理、批處理（定時SQL）功能對數據進一步加工、聚合處理，通過消費與投遞功能投遞業務數據到 OSS、MaxCompute 等。您可以通過訪問日誌服務（SLS） [ 20] 官網文檔等方式進一步瞭解 SLS 各種功能，助力您的業務發展。

總結

SLS SDK 通過適配 HarmonyOS NDK，並提供原生 ArkTS 語言原生 API 的方式，使開發者能夠確保應用程序在 HarmonyOS 操作系統上實現無縫對接和高效利用 SLS 功能，可以有效提升應用的穩定性和性能。SDK 提供的異步日誌寫入、日誌聚合壓縮上傳、緩存控制、自定義標識、斷點續傳、日誌上下文查看等豐富特性，可以簡化日誌管理流程，提升故障排查、性能優化、資源利用監控、安全防範等方面的能力。

此外，藉助 SLS 的強大平臺功能，如實時查詢、可視化分析、數據加工處理等等能力，不僅能夠快速定位問題，優化應用性能，還能夠在滿足數據合規性要求的同時，基於業務日誌構建全面的運維監控體系，爲數字化運營決策提供有效支持。

除了以上能力外，SLS 還提供基於 OTel（OpenTelemetry）協議的多平臺數據採集插件，您可以藉助這些插件實現端到端的 Trace 數據採集和分析能力。