# ohos_logan **Repository Path**: cbbgs/ohos_logan ## Basic Information - **Project Name**: ohos_logan - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-26 - **Last Updated**: 2026-02-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Logan ## 简介 > Logan 是美团开源的大前端日志系统，本项目是 Logan 的 OpenHarmony/HarmonyOS 版本 SDK。提供日志的收集、存储、加密和上传功能，支持高性能的 mmap 写入和 AES 加密存储。 ## 下载安装 ```shell ohpm install @ohos/logan ``` OpenHarmony ohpm环境配置等更多内容，请参考 [如何安装OpenHarmony ohpm包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md) 。 ## 使用说明 ### 导入组件 ```typescript import { Logan, LoganConfig, SendLogCallback } from '@ohos/logan'; ``` ### 初始化 ```typescript import { common } from '@kit.AbilityKit'; // 获取应用上下文 const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext; // 配置加密密钥（16字节） const encryptKey16: Uint8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]); const encryptIv16: Uint8Array = new Uint8Array([16, 15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1]); // 构建配置 const config: LoganConfig = LoganConfig.Builder() .setCachePath(context.cacheDir + '/logan_cache') // mmap 缓存目录 .setPath(context.filesDir + '/logan_files') // 日志文件存储目录 .setMaxFile(10) // 单文件最大 10MB .setDay(7) // 日志保留 7 天 .setEncryptKey16(encryptKey16) // AES 加密密钥 .setEncryptIV16(encryptIv16) // AES 初始化向量 .build(); // 初始化 Logan Logan.init(config); ``` ### 写入日志 ```typescript // 写入日志，type 为日志类型（自定义整数） Logan.w('这是一条日志信息', 1); Logan.w('用户点击了按钮', 2); Logan.w('网络请求完成', 3); ``` ### 刷新日志到文件 ```typescript // 将内存中的日志立即刷新到磁盘 Logan.f(); ``` ### 获取日志文件信息 ```typescript // 获取所有日志文件的日期和大小 const filesInfo: Record | null = await Logan.getAllFilesInfo(); if (filesInfo) { for (const date in filesInfo) { console.info(`日期: ${date}, 大小: ${filesInfo[date]} bytes`); } } ``` ### 发送日志（简化方式） ```typescript const callback: SendLogCallback = { onLogSendCompleted: (statusCode: number, data: ArrayBuffer): void => { if (statusCode >= 200 && statusCode < 300) { console.info('日志上传成功'); } else { console.error('日志上传失败，状态码：' + statusCode); } } }; Logan.s1( 'https://your-server.com/logan/upload', // 上传地址 '2026-02-05', // 日志日期 'your-app-id', // 应用ID 'user-union-id', // 用户ID 'device-id', // 设备ID '1.0.0', // 构建版本 '1.0.0', // 应用版本 callback // 回调 ); ``` ### 发送日志（自定义请求头） ```typescript const headers: Record = { 'appId': 'your-app-id', 'deviceId': 'device-id', 'customHeader': 'customValue' }; Logan.s2( 'https://your-server.com/logan/upload', '2026-02-05', headers, callback ); ``` ### 开启调试模式 ```typescript // 开启调试模式，会输出更多日志信息 Logan.setDebug(true); ``` ### 监听日志状态 ```typescript import { OnLoganProtocolStatus } from '@ohos/logan'; const statusListener: OnLoganProtocolStatus = { loganProtocolStatus: (cmd: string, code: number): void => { console.info(`Logan 状态回调 - 命令: ${cmd}, 状态码: ${code}`); } }; Logan.setOnLoganProtocolStatus(statusListener); ``` ## 接口说明 ### Logan 核心 API | 方法名 | 参数 | 返回值 | 说明 | | ------ | ---- | ------ | ---- | | `init(config)` | `LoganConfig` | `void` | 初始化日志系统 | | `w(log, type)` | `string, number` | `void` | 写入一条日志 | | `f()` | - | `void` | 刷新日志到磁盘 | | `s(dates, runnable)` | `string[], SendLogRunnable` | `void` | 批量发送日志 | | `s1(url, date, ...)` | 多参数 | `void` | 简化的日志发送 | | `s2(url, date, headers, callback)` | 多参数 | `void` | 自定义请求头发送 | | `getAllFilesInfo()` | - | `Promise \| null>` | 获取日志文件信息 | | `setDebug(debug)` | `boolean` | `void` | 设置调试模式 | | `setOnLoganProtocolStatus(listener)` | `OnLoganProtocolStatus` | `void` | 设置状态监听器 | ### LoganConfig.Builder 配置方法 | 方法名 | 参数 | 默认值 | 说明 | | ------ | ---- | ------ | ---- | | `setCachePath(path)` | `string` | - | mmap 缓存目录（必填） | | `setPath(path)` | `string` | - | 日志文件存储目录（必填） | | `setMaxFile(mb)` | `number` | `10` | 单个日志文件最大容量（MB） | | `setDay(days)` | `number` | `7` | 日志保留天数 | | `setEncryptKey16(key)` | `Uint8Array` | - | AES 16位加密密钥（必填） | | `setEncryptIV16(iv)` | `Uint8Array` | - | AES 16位初始化向量（必填） | | `setMinSDCard(mb)` | `number` | `50` | 最小剩余存储空间（MB） | | `build()` | - | `LoganConfig` | 构建配置对象 | ### SendLogCallback 回调接口 | 方法名 | 参数 | 说明 | | ------ | ---- | ---- | | `onLogSendCompleted(statusCode, data)` | `number, ArrayBuffer` | 日志发送完成回调 | ### OnLoganProtocolStatus 状态监听接口 | 方法名 | 参数 | 说明 | | ------ | ---- | ---- | | `loganProtocolStatus(cmd, code)` | `string, number` | 日志操作状态回调 | ## 技术特性 - **AES 加密**：日志内容采用 AES 加密存储，保护敏感信息 - **mmap 高性能写入**：使用内存映射技术，避免频繁 I/O，提升写入性能 - **Worker 线程隔离**：日志写入在独立线程执行，不阻塞主线程 - **跨平台一致性**：与 Android Logan SDK 行为保持一致 - **Native C++ 实现**：核心逻辑由 C++ 实现，通过 N-API 桥接 ## 约束与限制 在下述版本验证通过： - DevEco Studio NEXT Developer Beta3: (5.0.3.530), SDK: API12 (5.0.0.35(SP3)) ## 目录结构 ``` |---- ohos_logan | |---- entry # 示例代码文件夹 | |---- library # Logan 库文件夹 | | |---- src | | | └── main | | | |---- cpp # C++ Native 代码 | | | | |---- logan # Logan 桥接层 | | | | | |---- include/logan_ohos.h | | | | | └── src/logan_ohos.cpp | | | | |---- thirdparty/Logan # Logan C 核心库 | | | | └── CMakeLists.txt | | | └── ets | | | |---- logan # ArkTS 实现 | | | | |---- Logan.ets # 主入口类 | | | | |---- LoganConfig.ets # 配置类 | | | | |---- CLoganProtocol.ets # C 层协议 | | | | |---- LoganControlCenter.ets # 控制中心 | | | | |---- LoganThread.ets # 线程管理 | | | | |---- SendLogRunnable.ets # 发送任务基类 | | | | |---- SendLogDefaultRunnable.ets # 默认发送实现 | | | | └── ... # 其他工具类 | | | └── workers | | | └── LoganWorker.ets # Worker 线程 | | |---- Index.ets # 对外接口 | |---- README.md # 英文说明 | |---- README_zh.md # 中文说明 ``` ## 贡献代码 使用过程中发现任何问题都可以提 [Issue]() ，当然，也非常欢迎发 [PR]() 共建。 ## 开源协议 本项目基于 [MIT License](./LICENSE) ，请自由地享受和参与开源。