**日志服务 HarmonyOS NEXT 日志采集最佳实践**

**背景信息**

随着数字化新时代的全面展开以及5G与物联网（IoT）技术的迅速普及，操作系统正面临前所未有的变革需求。在这个背景下，华为公司自主研发的鸿蒙操作系统（HarmonyOS）应运而生，旨在满足万物互联时代的多元化设备接入、高效协同和安全可靠运行的需求。HarmonyOS 不仅着眼于智能手机市场，更是全球首个面向全场景智能生态的操作系统，支持从手机、平板电脑到智能家居、穿戴设备乃至工业控制等多种终端形态。2024年1月18日正式推出 HarmonyOS NEXT 鸿蒙星河开发者预览，该系统仅支持运行鸿蒙原生应用，不再兼容Android系统应用。深圳市于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），请参见开通日志服务。
• 已创建好对应的Project和Logstore，请参加管理Project和管理Logstore。
• 已创建并获取AccessKey，请参见访问密钥。阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维。RAM用户需具备操作日志服务（SLS）资源的权限。具体操作，请参见为RAM用户授权。
• [可选] 搭建HarmonyOS开发环境。开发鸿蒙应用需要使用HarmonyOS的IDE进行开发，具体内容请参考HarmonyOS官网开发文档。

**日志采集**

**安装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是通过STS方式获取时才需要
);

参数说明：

**日志采集**

完成SDK的初始化之后，可以通过以下方式完成日志的采集。

aliyunLog.addLog(new Map(
[
// 根据实际业务需要，调整您需要上报的业务字段
["from", "Home"],
["page", "HomePage"],
]
));

更多SDK使用相关的信息，建议您参考SLS官网文档 HarmonyOS SDK。

**日志使用**

**场景一：查询和可视化分析**

数据通过SDK采集上来之后，我们可以通过SLS控制台进行日志的查询和分析。

首先在SLS控制台Project列表中找到您的Project，并进入到Project页面。如下：

接着，在左侧日志库菜单中找到您的Logstore。如下：



如果Logstore没有开启索引，在您打开Logstore页面之后，会收到一个“未开启日志库索引”的提示框。您可以通过Logstore页面右上角的开启索引按钮来配置相关字段的索引。配置索引的具体方式可以参考创建索引这篇文档。本文示例的Logstore已经对以下字段进行了索引配置：

索引开启后，即可在Logstore页面看到我们上报的日志信息，如下：

注意：如果您的日志是在开启索引之前写入的，您需要重建索引后才能看到历史写入的数据。如何重建索引？您可以参考文档重建索引。

**可视化分析示例一：**分析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 的页面数据。请参考更多关于查询语法的信息。
• “|”之后的部分，是通过SQL语句对过滤出来的数据进行分析，即：通过date_trunc语句把时间对齐到分钟级别，然后使用count(*)计算出每分钟页面的访问次数。请参考更多关于分析语法的信息。

通过SLS可视化能力，可以对查询分析的结果使用丰富的图表展示，如下图是通过“线图Pro”类型的图表，按照时间升序展示每分钟的页面访问次数。

可视化分析示例二：分析CartPage页面的访问来源

基于示例数据，可以使用如下查询分析语句查询Cart页面的来源分布：

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

备注：因为from是SQL的保留字段，因此示例中使用了双引号""对from进行包装。



下图是通过饼图Pro类型的图表，绘制的来源页面分布。

SLS拥有非常强大的可视化分析能力，以上仅是非常简单的示例。实际使用中，可能会涉及到多种指标的同比/环比，漏斗转化实时分析等等。SLS对此提供了非常灵活和丰富的能力进行支持。更多信息可以参考查询与分析以及可视化。

**场景二：日志加工处理**

如果从鸿蒙设备上采集到的原始数据格式没有事先约定好，或者数据格式较为复杂，或者需要对个别字段做富化/脱敏等，您可以使用SLS数据加工能力对原始数据做富化和清洗。您可以参考以下步骤。

1. [可选] 新增一个Logstore用于存储加工处理后的数据，如下：

可根据实际业务的需要，提前对该Logstore进行索引等配置。

1. 进入到数据加工配置页面

您可以通过Logstore名称右侧的“数据加工”超链接进入到数据加工配置页面。

1. 配置数据加工任务

如上图，您可以参考以下步骤配置数据加工任务

• 1. 把目标数据加入到测试数据，用于验证数据加工脚本是否符合预期。
  2. 在脚本编辑区域，根据实际业务需要输入数据加工脚本规则，示例如下：

富化\_\_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")

关于数据加工脚本支持的语法，您可以参考数据加工语法。

• 1. 脚本编写完成后，您可以通过右上角“预览数据”按钮验证数据加工的结果。

如下图，是以上数据加工脚本的预览结果：

数据加工预览结果符合预期后，您就可以保存当前数据加工任务了，后续的具体操作请参考创建数据加工任务。

**其他场景**

除了上文中提到的查询与可视化分析、日志加工处理之外，SLS还支持基于业务日志创建自定义告警监控业务，通过流处理、批处理（定时SQL）功能对数据进一步加工、聚合处理，通过消费与投递功能投递业务数据到OSS、MaxCompute等。您可以通过访问日志服务（SLS）官网文档等方式进一步了解SLS各种功能，助力您的业务发展。

**总结**

SLS SDK 通过适配 HarmonyOS NDK，并提供原生ArkTS语言原生API的方式，使开发者能够确保应用程序在HarmonyOS操作系统上实现无缝对接和高效利用SLS功能，可以有效提升应用的稳定性和性能。SDK提供的异步日志写入、日志聚合压缩上传、缓存控制、自定义标识、断点续传、日志上下文查看等丰富特性，可以简化日志管理流程，提升故障排查、性能优化、资源利用监控、安全防范等方面的能力。此外，借助SLS的强大平台功能，如实时查询、可视化分析、数据加工处理等等能力，不仅能够快速定位问题，优化应用性能，还能够在满足数据合规性要求的同时，基于业务日志构建全面的运维监控体系，为数字化运营决策提供有效支持。

除了以上能力外，SLS还提供基于OTel（OpenTelemetry）协议的多平台数据采集插件，您可以借助这些插件实现端到端的Trace数据采集和分析能力。

• 通过OpenTelemetry接入Android Trace数据
• 通过OpenTelemetry接入iOS Trace数据
• 通过OpenTelemetry接入Flutter/Dart Trace数据
• 通过OpenTelemetry接入C++ Trace数据
• 接入Web Trace数据
• 接入小程序Trace数据

更多关于Trace数据采集和使用相关的内容，你可以参考SLS Trace服务。欢迎您试用！

附：

1. 阿里云 SLS 服务介绍： https://help.aliyun.com/product/28958.html
2. 阿里云 SLS Trace服务介绍：<https://help.aliyun.com/document_detail/208889.html>
3. 阿里云 SLS 可视化介绍：https://help.aliyun.com/zh/sls/developer-reference/visualization-development/
4. 联系阿里云 SLS