From fcce0ba7c79ee68ee55f771c443eac019ee1220c Mon Sep 17 00:00:00 2001 From: zengyawen Date: Tue, 15 Mar 2022 15:27:40 +0800 Subject: [PATCH 1/3] add log.h Signed-off-by: zengyawen --- zh-cn/native_sdk/dfx/log.h | 225 +++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 zh-cn/native_sdk/dfx/log.h diff --git a/zh-cn/native_sdk/dfx/log.h b/zh-cn/native_sdk/dfx/log.h new file mode 100644 index 00000000..7b9b3777 --- /dev/null +++ b/zh-cn/native_sdk/dfx/log.h @@ -0,0 +1,225 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef HIVIEWDFX_HILOG_H +#define HIVIEWDFX_HILOG_H +/** + * @addtogroup HiLog + * @{ + * + * @brief HiLog模块实现日志打印功能。 + * + * 开发者可以通过使用这些接口实现日志相关功能，输出日志时可以指定日志类型、所属业务领域、日志TAG标识、日志级别等。 + * + * @syscap SystemCapability.HiviewDFX.HiLog + * + * @since 8 + */ + +/** + * @file log.h + * + * @brief HiLog模块日志接口定义，通过这些接口实现日志打印相关功能。 + * + * 用户输出日志时，先定义日志所属业务领域、日志TAG，然后按照类型、级别选择对应API，指定参数隐私标识输出日志内容。\n + * 业务领域：指定日志所对应的业务领域，用户自定义使用，用于标识业务的子系统、模块。16进制整数，范围0x0~0xFFFF。建议业务领域划分形式为0xAAABB，其中AAA为子系统，BB为模块。\n + * 日志TAG：字符串常量，用于标识调用所在的类或者业务行为。\n + * 日志级别：DEBUG、INFO、WARN、ERROR、FATAL。\n + * 参数格式：类printf的%方式，包括格式字符串（包括参数类型标识）和变参。\n + * 隐私参数标识：在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。注意：每个参数未指定隐私标识时，缺省为隐私。\n + * + * 使用示例：\n + * 定义业务领域、TAG：\n + * #define LOG_DOMAIN MY_SUBSYSTEM_MODULE // MY_SUBSYSTEM_MODULE=0x00201,其中002为子系统，01为模块\n + * #define LOG_TAG "MY_TAG"\n + * 日志打印：\n + * HILOG_WARN({@link LOG_APP}, "Failed to visit %{private}s, reason:%{public}d.", url, errno);\n + * 结果输出：\n + * 05-06 15:01:06.870 1051 1051 W 00201/MY_TAG: Failed to visit , reason:503.\n + * + * @since 8 + */ +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief 日志所对应的业务领域，用于标识业务的子系统、模块。 + * + * 16进制整数，有效范围0x0~0xFFFF，超过自动截掉高位。\n + * 建议业务领域划分形式为0xAAABB，其中AAA为子系统，BB为模块。\n + * + * @since 8 + */ +#ifndef LOG_DOMAIN +#define LOG_DOMAIN 0 +#endif + +/** + * @brief 字符串常量，标识调用所在的类或者业务行为。 + * + * @since 8 + */ +#ifndef LOG_TAG +#define LOG_TAG NULL +#endif + +/** + * @brief 日志类型。 + * + * 该枚举类型用于定义应用开发者可以使用的日志类型。当前有应用日志LOG_APP。\n + * + * @since 8 + */ +enum LogType +{ + /** 应用日志 */ + LOG_APP = 0, +}; + +/** + * @brief 日志级别。 + * + * 该枚举类型用于定义日志级别。各级别建议使用方式：\n + * DEBUG：比INFO级别更详细的流程记录，通过该级别的日志可以更详细地分析业务流程和定位分析问题。DEBUG级别的日志在正式发布版本中默认不会被打印，只有在调试版本或打开调试开关的情况下才会打印。\n + * INFO：用来记录业务关键流程节点，可以还原业务的主要运行过程；用来记录非正常情况信息，但这些情况都是可以预期的(如无网络信号、登录失败等)。这些日志都应该由该业务内处于支配地位的模块来记录，避免在多个被调用的模块或低级函数中重复记录。\n + * WARN：发生了较为严重的非预期情况，但是对用户影响不大，程序可以自动恢复或通过简单的操作就可以恢复的问题。\n + * ERROR：程序或功能发生了错误，该错误会影响功能的正常运行或用户的正常使用，可以恢复但恢复代价较高，如重置数据等。\n + * FATAL：重大致命异常，表明程序或功能即将崩溃，故障无法恢复。\n + * + * @since 8 + */ +enum LogLevel +{ + /** DEBUG日志级别，使用HILOG_DEBUG接口打印 */ + LOG_DEBUG = 3, + /** INFO日志级别，使用HILOG_INFO接口打印 */ + LOG_INFO = 4, + /** WARN日志级别，使用HILOG_WARN接口打印 */ + LOG_WARN = 5, + /** ERROR日志级别，使用HILOG_ERROR接口打印 */ + LOG_ERROR = 6, + /** FATAL日志级别，使用HILOG_FATAL接口打印 */ + LOG_FATAL = 7, +}; + +/** + * @brief 写日志接口。 + * + * 指定日志类型、日志级别、业务领域、TAG，按照类printf格式类型和隐私指示确定需要输出的变参。 + * + * @param type 日志类型，三方应用日志类型为LOG_APP。 + * @param level 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 + * @param domain 日志业务领域，16进制整数，范围0x0~0xFFFF。建议业务领域划分形式为0xAAABB，其中AAA为子系统，BB为模块。 + * @param tag 日志TAG，字符串，标识调用所在的类或者业务行为。 + * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 + * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @return 大于等于0表示成功；小于0表示失败。 + * + * @since 8 + */ +int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, ...) + __attribute__((__format__(os_log, 5, 6))); + +/** + * @brief 检查指定业务领域、TAG、级别的日志是否可以打印。 + * + * @param domain 指定日志业务领域。 + * @param tag 指定日志TAG。 + * @param level 指定日志level。 + * @return 如果指定domain、tag、level日志可以打印则返回true；否则返回false。 + * + * @since 8 + */ +bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); + +/** + * @brief DEBUG级别写日志，宏封装接口。 + * + * 使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。\n + * + * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 + * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 + * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @see OH_LOG_Print + * + * @since 8 + */ +#define OH_LOG_DEBUG(type, ...) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) + +/** + * @brief INFO级别写日志，宏封装接口。 + * + * 使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。\n + * + * @param type 日志类型，三方应用日志类型为LOG_APP。 + * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 + * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @see OH_LOG_Print + * + * @since 8 + */ +#define OH_LOG_INFO(type, ...) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) + +/** + * @brief WARN级别写日志，宏封装接口。 + * + * 使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 + * + * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 + * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 + * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @see OH_LOG_Print + * + * @since 8 + */ +#define OH_LOG_WARN(type, ...) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) + +/** + * @brief ERROR级别写日志，宏封装接口。 + * + * 使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 + * + * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 + * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 + * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @see OH_LOG_Print + * + * @since 8 + */ +#define OH_LOG_ERROR(type, ...) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) + +/** + * @brief FATAL级别写日志，宏封装接口。 + * + * 使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。\n + * + * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 + * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 + * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @see OH_LOG_Print + * + * @since 8 + */ +#define OH_LOG_FATAL(type, ...) ((void)HiLogPrint((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) + +#ifdef __cplusplus +} +#endif +/** @} */ +#endif // HIVIEWDFX_HILOG_H \ No newline at end of file -- Gitee From 3af9137345e620fb55f6fcdc5b3030a2561c0be4 Mon Sep 17 00:00:00 2001 From: zengyawen Date: Tue, 15 Mar 2022 16:09:47 +0800 Subject: [PATCH 2/3] add log.h Signed-off-by: zengyawen --- zh-cn/native_sdk/dfx/log.h | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/zh-cn/native_sdk/dfx/log.h b/zh-cn/native_sdk/dfx/log.h index 7b9b3777..059fb94e 100644 --- a/zh-cn/native_sdk/dfx/log.h +++ b/zh-cn/native_sdk/dfx/log.h @@ -34,20 +34,20 @@ * @brief HiLog模块日志接口定义，通过这些接口实现日志打印相关功能。 * * 用户输出日志时，先定义日志所属业务领域、日志TAG，然后按照类型、级别选择对应API，指定参数隐私标识输出日志内容。\n - * 业务领域：指定日志所对应的业务领域，用户自定义使用，用于标识业务的子系统、模块。16进制整数，范围0x0~0xFFFF。建议业务领域划分形式为0xAAABB，其中AAA为子系统，BB为模块。\n - * 日志TAG：字符串常量，用于标识调用所在的类或者业务行为。\n + * 业务领域：指定日志所对应的业务领域，用户自定义使用，用于标识业务的子系统、模块。16进制整数，范围0x0~0xFFFF。\n + * 日志TAG：字符串常量，用于标识调用所在的类或者业务。\n * 日志级别：DEBUG、INFO、WARN、ERROR、FATAL。\n * 参数格式：类printf的%方式，包括格式字符串（包括参数类型标识）和变参。\n * 隐私参数标识：在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。注意：每个参数未指定隐私标识时，缺省为隐私。\n * * 使用示例：\n * 定义业务领域、TAG：\n - * #define LOG_DOMAIN MY_SUBSYSTEM_MODULE // MY_SUBSYSTEM_MODULE=0x00201,其中002为子系统，01为模块\n + * #define LOG_DOMAIN 0x0201\n * #define LOG_TAG "MY_TAG"\n * 日志打印：\n * HILOG_WARN({@link LOG_APP}, "Failed to visit %{private}s, reason:%{public}d.", url, errno);\n * 结果输出：\n - * 05-06 15:01:06.870 1051 1051 W 00201/MY_TAG: Failed to visit , reason:503.\n + * 05-06 15:01:06.870 1051 1051 W 0201/MY_TAG: Failed to visit , reason:503.\n * * @since 8 */ @@ -62,7 +62,6 @@ extern "C" { * @brief 日志所对应的业务领域，用于标识业务的子系统、模块。 * * 16进制整数，有效范围0x0~0xFFFF，超过自动截掉高位。\n - * 建议业务领域划分形式为0xAAABB，其中AAA为子系统，BB为模块。\n * * @since 8 */ @@ -71,7 +70,7 @@ extern "C" { #endif /** - * @brief 字符串常量，标识调用所在的类或者业务行为。 + * @brief 字符串常量，标识调用所在的类或者业务。 * * @since 8 */ @@ -125,10 +124,10 @@ enum LogLevel * * @param type 日志类型，三方应用日志类型为LOG_APP。 * @param level 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 - * @param domain 日志业务领域，16进制整数，范围0x0~0xFFFF。建议业务领域划分形式为0xAAABB，其中AAA为子系统，BB为模块。 - * @param tag 日志TAG，字符串，标识调用所在的类或者业务行为。 + * @param domain 日志业务领域，16进制整数，范围0x0~0xFFFF。 + * @param tag 日志TAG，字符串，标识调用所在的类或者业务。 * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 - * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @param ... 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 * @return 大于等于0表示成功；小于0表示失败。 * * @since 8 @@ -155,7 +154,7 @@ bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); * * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 - * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @param ... 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 * @see OH_LOG_Print * * @since 8 @@ -169,7 +168,7 @@ bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); * * @param type 日志类型，三方应用日志类型为LOG_APP。 * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 - * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @param ... 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 * @see OH_LOG_Print * * @since 8 @@ -183,7 +182,7 @@ bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); * * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 - * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @param ... 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 * @see OH_LOG_Print * * @since 8 @@ -197,7 +196,7 @@ bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); * * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 - * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @param ... 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 * @see OH_LOG_Print * * @since 8 @@ -211,7 +210,7 @@ bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); * * @param type 日志类型，三方应用日志类型为{@link LOG_APP}。 * @param fmt 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 - * @param ... 与格式字符串里参数类型对应的参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 + * @param ... 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 * @see OH_LOG_Print * * @since 8 -- Gitee From f105ba199ec7bdc37b912c79ee008b3e3f4f7a6e Mon Sep 17 00:00:00 2001 From: zengyawen Date: Tue, 15 Mar 2022 16:51:15 +0800 Subject: [PATCH 3/3] update docs Signed-off-by: zengyawen --- zh-cn/native_sdk/dfx/log.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/zh-cn/native_sdk/dfx/log.h b/zh-cn/native_sdk/dfx/log.h index 059fb94e..a0579bbd 100644 --- a/zh-cn/native_sdk/dfx/log.h +++ b/zh-cn/native_sdk/dfx/log.h @@ -105,15 +105,15 @@ enum LogType */ enum LogLevel { - /** DEBUG日志级别，使用HILOG_DEBUG接口打印 */ + /** DEBUG日志级别，使用OH_LOG_DEBUG接口打印 */ LOG_DEBUG = 3, - /** INFO日志级别，使用HILOG_INFO接口打印 */ + /** INFO日志级别，使用OH_LOG_INFO接口打印 */ LOG_INFO = 4, - /** WARN日志级别，使用HILOG_WARN接口打印 */ + /** WARN日志级别，使用OH_LOG_WARN接口打印 */ LOG_WARN = 5, - /** ERROR日志级别，使用HILOG_ERROR接口打印 */ + /** ERROR日志级别，使用OH_LOG_ERROR接口打印 */ LOG_ERROR = 6, - /** FATAL日志级别，使用HILOG_FATAL接口打印 */ + /** FATAL日志级别，使用OH_LOG_FATAL接口打印 */ LOG_FATAL = 7, }; -- Gitee