1 /* 2 * Copyright (c) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef HIVIEWDFX_HILOG_H 17 #define HIVIEWDFX_HILOG_H 18 /** 19 * @addtogroup HiLog 20 * @{ 21 * 22 * @brief Provides logging functions. 23 * 24 * For example, you can use these functions to output logs of the specified log type, service domain, log tag, 25 * and log level. 26 * 27 * @kit PerformanceAnalysisKit 28 * @syscap SystemCapability.HiviewDFX.HiLog 29 * 30 * @since 8 31 */ 32 33 /** 34 * @file log.h 35 * 36 * @brief Defines the logging functions of the HiLog module. 37 * 38 * Before outputting logs, you must define the service domain, and log tag, use the function with 39 * the specified log type and level, and specify the privacy identifier.\n 40 * <ul><li>Service domain: used to identify the subsystem and module of a service. Its value is a hexadecimal 41 * integer ranging from 0x0 to 0xFFFF. \n 42 * <li>Log tag: a string used to identify the class, file, or service.</li> \n 43 * <li>Log level: <b>DEBUG</b>, <b>INFO</b>, <b>WARN</b>, <b>ERROR</b>, and <b>FATAL</b></li> \n 44 * <li>Parameter format: a printf format string that starts with a % character, including format specifiers 45 * and variable parameters.</li> \n 46 * <li>Privacy identifier: {public} or {private} added between the % character and the format specifier in 47 * each parameter. Note that each parameter has a privacy identifier. If no privacy identifier is added, 48 * the parameter is considered to be <b>private</b>.</li></ul> \n 49 * 50 * Sample code:\n 51 * Defining the service domain and log tag:\n 52 * #include <hilog/log.h>\n 53 * #define LOG_DOMAIN 0x0201\n 54 * #define LOG_TAG "MY_TAG"\n 55 * Outputting logs:\n 56 * HILOG_WARN({@link LOG_APP}, "Failed to visit %{private}s, reason:%{public}d.", url, errno);\n 57 * Output result:\n 58 * 05-06 15:01:06.870 1051 1051 W 0201/MY_TAG: Failed to visit <private>, reason:503.\n 59 * 60 * @since 8 61 */ 62 #include <stdarg.h> 63 #include <stdbool.h> 64 65 #ifdef __cplusplus 66 extern "C" { 67 #endif 68 69 /** 70 * @brief Defines the service domain for a log file. 71 * 72 * The service domain is used to identify the subsystem and module of a service. Its value is a hexadecimal integer 73 * ranging from 0x0 to 0xFFFF. If the value is beyond the range, its significant bits are automatically truncated. \n 74 * 75 * @since 8 76 */ 77 #ifndef LOG_DOMAIN 78 #define LOG_DOMAIN 0 79 #endif 80 81 /** 82 * @brief Defines a string constant used to identify the class, file, or service. 83 * 84 * @since 8 85 */ 86 #ifndef LOG_TAG 87 #define LOG_TAG NULL 88 #endif 89 90 /** 91 * @brief Enumerates log types. 92 * 93 * Currently, <b>LOG_APP</b> is available. \n 94 * 95 * @since 8 96 */ 97 typedef enum { 98 /** Third-party application logs */ 99 LOG_APP = 0, 100 } LogType; 101 102 /** 103 * @brief Enumerates log levels. 104 * 105 * You are advised to select log levels based on their respective usage scenarios:\n 106 * <ul><li><b>DEBUG</b>: used for debugging and disabled from commercial releases</li> \n 107 * <li><b>INFO</b>: used for logging important system running status and steps in key processes</li> \n 108 * <li><b>WARN</b>: used for logging unexpected exceptions that have little impact on user experience and can 109 * automatically recover. Logs at this level are generally output when such exceptions are detected and 110 * captured.</li> \n 111 * <li><b>ERROR</b>: used for logging malfunction that affects user experience and cannot automatically 112 * recover</li>\n 113 * <li><b>FATAL</b>: used for logging major exceptions that have severely affected user experience and should 114 * not occur.</li></ul> \n 115 * 116 * @since 8 117 */ 118 typedef enum { 119 /** Debug level to be used by {@link OH_LOG_DEBUG} */ 120 LOG_DEBUG = 3, 121 /** Informational level to be used by {@link OH_LOG_INFO} */ 122 LOG_INFO = 4, 123 /** Warning level to be used by {@link OH_LOG_WARN} */ 124 LOG_WARN = 5, 125 /** Error level to be used by {@link OH_LOG_ERROR} */ 126 LOG_ERROR = 6, 127 /** Fatal level to be used by {@link OH_LOG_FATAL} */ 128 LOG_FATAL = 7, 129 } LogLevel; 130 131 /** 132 * @brief Outputs logs. 133 * 134 * You can use this function to output logs based on the specified log type, log level, service domain, log tag, 135 * and variable parameters determined by the format specifier and privacy identifier in the printf format. 136 * 137 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 138 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 139 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 140 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 141 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 142 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 143 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier 144 * in each parameter. \n 145 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 146 * in the format string. 147 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller 148 * than <b>0</b> otherwise. 149 * @since 8 150 */ 151 int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, ...) 152 __attribute__((__format__(os_log, 5, 6))); 153 154 /** 155 * @brief Checks whether logs of the specified service domain, log tag, and log level can be output. 156 * 157 * @param domain Indicates the service domain of logs. 158 * @param tag Indicates the log tag. 159 * @param level Indicates the log level. 160 * @return Returns <b>true</b> if the specified logs can be output; returns <b>false</b> otherwise. 161 * @since 8 162 */ 163 bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); 164 165 /** 166 * @brief Outputs debug logs. This is a function-like macro. 167 * 168 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at 169 * the beginning of the source file. \n 170 * 171 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 172 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the 173 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier 174 * in each parameter. \n 175 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 176 * in the format string. 177 * @see OH_LOG_Print 178 * @since 8 179 */ 180 #define OH_LOG_DEBUG(type, ...) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 181 182 /** 183 * @brief Outputs informational logs. This is a function-like macro. 184 * 185 * Before calling this function, define the log service domain and log tag. Generally, you need to define them 186 * at the beginning of the source file. \n 187 * 188 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 189 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 190 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in 191 * each parameter. \n 192 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 193 * in the format string. 194 * @see OH_LOG_Print 195 * @since 8 196 */ 197 #define OH_LOG_INFO(type, ...) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 198 199 /** 200 * @brief Outputs warning logs. This is a function-like macro. 201 * 202 * Before calling this function, define the log service domain and log tag. Generally, you need to define them 203 * at the beginning of the source file. \n 204 * 205 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 206 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the 207 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier 208 * in each parameter. \n 209 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 210 * in the format string. 211 * @see OH_LOG_Print 212 * @since 8 213 */ 214 #define OH_LOG_WARN(type, ...) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 215 216 /** 217 * @brief Outputs error logs. This is a function-like macro. 218 * 219 * Before calling this function, define the log service domain and log tag. Generally, you need to define 220 * them at the beginning of the source file. \n 221 * 222 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 223 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 224 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each 225 * parameter. \n 226 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 227 * in the format string. 228 * @see OH_LOG_Print 229 * @since 8 230 */ 231 #define OH_LOG_ERROR(type, ...) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 232 233 /** 234 * @brief Outputs fatal logs. This is a function-like macro. 235 * 236 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at 237 * the beginning of the source file. \n 238 * 239 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 240 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 241 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in 242 * each parameter. \n 243 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 244 * in the format string. 245 * @see OH_LOG_Print 246 * @since 8 247 */ 248 #define OH_LOG_FATAL(type, ...) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 249 250 /** 251 * @brief Defines the function pointer type for the user-defined log processing function. 252 * 253 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 254 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 255 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 256 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 257 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 258 * @param msg Indicates the log message itself, which is a formatted log string. 259 * @since 11 260 */ 261 typedef void (*LogCallback)(const LogType type, const LogLevel level, const unsigned int domain, const char *tag, 262 const char *msg); 263 264 /** 265 * @brief Set the user-defined log processing function. 266 * 267 * After calling this function, the callback function implemented by the user can receive all hilogs of the 268 * current process. 269 * Note that it will not change the default behavior of hilog logs of the current process, no matter whether this 270 * interface is called or not. \n 271 * 272 * @param callback Indicates the callback function implemented by the user. If you do not need to process hilog logs, 273 * you can transfer a null pointer. 274 * @since 11 275 */ 276 void OH_LOG_SetCallback(LogCallback callback); 277 278 #ifdef __cplusplus 279 } 280 #endif 281 /** @} */ 282 283 #ifdef HILOG_RAWFORMAT 284 #include "hilog/log_inner.h" 285 #endif 286 287 #endif // HIVIEWDFX_HILOG_C_H 288