log.h

Overview

Defines the logging functions of the HiLog module. Before outputting logs, you must define the service domain, and log tag, use the API with the specified log type and level, and specify the privacy identifier.
Service domain: service domain of logs. You can define the value as required. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed.
Log tag: a string used to identify the class, file, or service behavior.
Log level: DEBUG, INFO, WARN, ERROR, or FATAL.
Parameter format: printf format string, which starts with a % character, including a parameter type identifier and a variable parameter.
Privacy identifier: {public} or {private} added between the % character and the parameter type identifier in each parameter. Note: If no privacy identifier is added, the parameter is considered to be private.

File to include: <hilog/log.h>

Library: libhilog_ndk.z.so

System capability: SystemCapability.HiviewDFX.HiLog

Since: 8

Related module: HiLog

Summary

Enum

Name	typedef Keyword	Description
LogType	LogType	Enumerates the log types. You can use this function to specify the type of output logs. Currently, only LOG_APP is available.
LogLevel	LogLevel	Enumerates the log levels. You are advised to select log levels based on their respective use cases. Log levels: DEBUG: provides more detailed process information than INFO logs to help developers analyze service processes and locate faults. DEBUG logs are not recorded in official versions by default. They are available in debug versions or in official versions with the debug function enabled. INFO: indicates the key service process nodes and exceptions (for example, no network signal or login failure) that occur during service running. These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions. WARN: indicates a severe, unexpected fault that has little impact on users and can be rectified by the programs themselves or through simple operations. ERROR: indicates a program or functional error that affects the normal running or use of the functionality and can be fixed at a high cost, for example, by resetting data. FATAL: indicates that a program or functionality is about to crash and the fault cannot be rectified.
PreferStrategy	PreferStrategy	Enumerates the preference strategies. This enum is used in OH_LOG_SetLogLevel. The minimum log level that takes effect varies according to the strategy.

Macros

Name	Description
OH_LOG_DEBUG(type, ...) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))	Indicates DEBUG logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file. Since: 8
OH_LOG_INFO(type, ...) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))	Indicates INFO logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file. Since: 8
OH_LOG_WARN(type, ...) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))	Indicates WARN logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file. Since: 8
OH_LOG_ERROR(type, ...) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))	Indicates ERROR logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file. Since: 8
OH_LOG_FATAL(type, ...) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))	Indicates FATAL logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file. Since: 8
LOG_DOMAIN	Specifies the service domain of the output log. The default value is 0. The value range is 0x0 to 0xFFFF. If the value of domainID exceeds the range, the log cannot be printed. Since: 8
LOG_TAG	Identifies the class or service behavior where the log is called. The value is a string constant, which is NULL by default. The maximum length is 31 bytes. If the length exceeds 31 bytes, the log will be truncated. The value must be a non-null string. Otherwise, the log cannot be printed. Chinese characters are not recommended, because they may cause garbled characters or alignment issues. Since: 8

Functions

Name	typedef Keyword	Description
int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char tag, const char fmt, ...)	-	Outputs logs of the specified type, level, domain, tag, and variables determined by the format specifier and privacy identifier in the printf format.
int OH_LOG_PrintMsg(LogType type, LogLevel level, unsigned int domain, const char tag, const char message)	-	Outputs constant log strings of the specified type, level, domain, and tag.
int OH_LOG_PrintMsgByLen(LogType type, LogLevel level, unsigned int domain, const char tag, size_t tagLen, const char message, size_t messageLen)	-	Outputs log constant strings of the specified domain, tag, and level. The tag and string length must be specified. Unlike OH_LOG_PrintMsg, this API allows strings without terminators.
int OH_LOG_VPrint(LogType type, LogLevel level, unsigned int domain, const char tag, const char fmt, va_list ap)	-	Outputs logs of the specified type, level, domain, tag, and variables determined by the format specifier and privacy identifier in the printf format. The variables are of the va_list type.
bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level)	-	Checks whether logs of the specified service domain, tag, and level can be printed.
typedef void (LogCallback)(const LogType type, const LogLevel level, const unsigned int domain, const char tag, const char *msg)	LogCallback	Customizes the processing of HiLog logs in the callback.
void OH_LOG_SetCallback(LogCallback callback)	-	Registers a callback function. After this function is called, the custom callback can receive all HiLog logs of the current process. Note that whether this API is called or not, it does not change the default log processing of the current process.
void OH_LOG_SetMinLogLevel(LogLevel level)	-	Sets the minimum log level.
void OH_LOG_SetLogLevel(LogLevel level, PreferStrategy prefer)	-	Sets the minimum log level of the current application process. You can configure different preference strategies.

NOTE

If the set log level is lower than the global log level, the OH_LOG_SetMinLogLevel() setting does not take effect.

In the debug applications, the OH_LOG_SetMinLogLevel() and OH_LOG_SetLogLevel() functions do not take effect.

Enum Description

LogType

enum LogType

Description

Enumerates the log types. You can use this function to specify the type of output logs. Currently, only LOG_APP is available.

Since: 8

Enum Item	Description
LOG_APP = 0	Application log.

LogLevel

enum LogLevel

Description

Enumerates the log levels. You are advised to select log levels based on their respective use cases. Log levels:
DEBUG: provides more detailed process information than INFO logs to help developers analyze service processes and locate faults. DEBUG logs are not recorded in official versions by default. They are available in debug versions or in official versions with the debug function enabled.
INFO: indicates the key service process nodes and exceptions (for example, no network signal or login failure) that occur during service running. These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions.
WARN: indicates a severe, unexpected fault that has little impact on users and can be rectified by the programs themselves or through simple operations.
ERROR: indicates a program or functional error that affects the normal running or use of the functionality and can be fixed at a high cost, for example, by resetting data.
FATAL: indicates that a program or functionality is about to crash and the fault cannot be rectified.

Since: 8

Enum Item	Description
LOG_DEBUG = 3	DEBUG level to be used by OH_LOG_DEBUG.
LOG_INFO = 4	INFO level to be used by OH_LOG_INFO.
LOG_WARN = 5	WARN level to be used by OH_LOG_WARN.
LOG_ERROR = 6	ERROR level to be used by OH_LOG_ERROR.
LOG_FATAL = 7	FATAL level to be used by OH_LOG_FATAL.

PreferStrategy

enum PreferStrategy

Description

Enumerates the preference strategies. This enum is used in OH_LOG_SetLogLevel. The minimum log level that takes effect varies according to the strategy.

Since: 21

Enum Item	Description
UNSET_LOGLEVEL = 0	The setting is cleared. The minimum log level that actually takes effect is the system-controlled minimum log level.
PREFER_CLOSE_LOG = 1	The minimum log level that actually takes effect is the larger value of the new log level and the system-controlled minimum log level.
PREFER_OPEN_LOG = 2	The minimum log level that actually takes effect is the smaller value of the new log level and the system-controlled minimum log level.

Function Description

OH_LOG_Print()

int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, ...)

Description

Outputs logs of the specified type, level, domain, tag, and variables determined by the format specifier and privacy identifier in the printf format.

Since: 8

Parameters

Name	Description
LogType type	Log type. The type for third-party applications is defined by LOG_APP.
LogLevel level	Log level. The value can be LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, and LOG_FATAL.
unsigned int domain	Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed.
const char *tag	Log tag, which is a string used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.
const char *fmt	Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each parameter.
...	Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string.

Returns

Type	Description
int	0 or a larger value if the operation is successful; a value smaller than 0 otherwise. Possible failure causes: The LogLevel passed in is lower than the allowed log level; the domain is out of range; the tag is a null pointer; the CPU is overloaded; the memory is insufficient; the number of logs on the device is too large.

OH_LOG_PrintMsg()

int OH_LOG_PrintMsg(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *message)

Description

Outputs constant log strings of the specified type, level, domain, and tag.

Since: 18

Parameters

Name	Description
LogType type	Log type. The type for third-party applications is defined by LOG_APP.
LogLevel level	Log level. The value can be LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, and LOG_FATAL.
unsigned int domain	Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed.
const char *tag	Log tag, which is a string used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.
const char *message	Constant log string.

Returns

Type	Description
int	0 or a larger value if the operation is successful; a value smaller than 0 otherwise. Possible failure causes: The LogLevel passed in is lower than the allowed log level; the domain is out of range; the tag is a null pointer; the CPU is overloaded; the memory is insufficient; the number of logs on the device is too large.

OH_LOG_PrintMsgByLen()

int OH_LOG_PrintMsgByLen(LogType type, LogLevel level, unsigned int domain, const char *tag, size_t tagLen, const char *message, size_t messageLen)

Description

Outputs log constant strings of the specified domain, tag, and level. The tag and string length must be specified. Unlike OH_LOG_PrintMsg, this API allows strings without terminators.

Since: 18

Parameters

Name	Description
LogType type	Log type. The type for third-party applications is defined by LOG_APP.
LogLevel level	Log level. The value can be LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, and LOG_FATAL.
unsigned int domain	Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed.
const char *tag	Log tag, which is a string used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.
size_t tagLen	Length of the tag.
const char *message	Constant log string.
size_t messageLen	Length of the constant string, which is less than 3500 characters.

Returns

Type	Description
int	0 or a larger value if the operation is successful; a value smaller than 0 otherwise. Possible failure causes: The LogLevel passed in is lower than the allowed log level; the domain is out of range; the tag is a null pointer; the CPU is overloaded; the memory is insufficient; the number of logs on the device is too large.

OH_LOG_VPrint()

int OH_LOG_VPrint(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, va_list ap)

Description

Outputs logs of the specified type, level, domain, tag, and variables determined by the format specifier and privacy identifier in the printf format. The variables are of the va_list type.

Since: 18

Parameters

Name	Description
LogType type	Log type. The type for third-party applications is defined by LOG_APP.
LogLevel level	Log level. The value can be LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, and LOG_FATAL.
unsigned int domain	Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed.
const char *tag	Log tag, which is a string used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.
const char *fmt	Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each parameter.
va_list ap	Parameter list of the va_list type that corresponds to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string.

Returns

Type	Description
int	0 or a larger value if the operation is successful; a value smaller than 0 otherwise. Possible failure causes: The LogLevel passed in is lower than the allowed log level; the domain is out of range; the tag is a null pointer; the CPU is overloaded; the memory is insufficient; the number of logs on the device is too large.

OH_LOG_IsLoggable()

bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level)

Description

Checks whether logs of the specified service domain, tag, and level can be printed.

Since: 8

Parameters

Name	Description
unsigned int domain	Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed.
const char *tag	Log tag, which is a string used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.
LogLevel level	Log level. The value can be LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, and LOG_FATAL.

Returns

Type	Description
bool	true if the specified logs can be output; false otherwise.

OH_LOG_DEBUG()

OH_LOG_DEBUG(type, ...)((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))

Description

Indicates DEBUG logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file.

Since: 8

Parameters

Name	Description
type	Log type. The third-party application log type is LOG_APP.
fmt	Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each parameter.
...	Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string.

See also

OH_LOG_Print

OH_LOG_INFO()

OH_LOG_INFO(type, ...)((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))

Description

Indicates INFO logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file.

Since: 8

Parameters

Name	Description
type	Log type. The type for third-party applications is defined by LOG_APP.
fmt	Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each parameter.
...	Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string.

See also

OH_LOG_Print

OH_LOG_WARN()

OH_LOG_WARN(type, ...)((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))

Description

Indicates WARN logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file.

Since: 8

Parameters

Name	Description
type	Log type. The third-party application log type is LOG_APP.
fmt	Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each parameter.
...	Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string.

See also

OH_LOG_Print

OH_LOG_ERROR()

OH_LOG_ERROR(type, ...)((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))

Description

Indicates ERROR logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file.

Since: 8

Parameters

Name	Description
type	Log type. The third-party application log type is LOG_APP.
fmt	Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each parameter.
...	Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string.

See also

OH_LOG_Print

OH_LOG_FATAL()

OH_LOG_FATAL(type, ...)((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))

Description

Indicates FATAL logs. This is a function-like macro. Before using this macro, define LOG_DOMAIN and LOG_TAG at the beginning of the source file.

Since: 8

Parameters

Name	Description
type	Log type. The third-party application log type is LOG_APP.
fmt	Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each parameter.
...	Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string.

See also

OH_LOG_Print

LogCallback()

typedef void (*LogCallback)(const LogType type, const LogLevel level, const unsigned int domain, const char *tag, const char *msg)

Description

Customizes the processing of HiLog logs in the callback.

Since: 11

Parameters

Name	Description
const LogType type	Log type. The third-party application log type is LOG_APP.
const LogLevel level	Log level. The value can be LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, and LOG_FATAL.
const unsigned int domain	Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed.
const char *tag	Log tag, which is a string used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.
const char *msg	Log content, which is made up of formatted log strings.

OH_LOG_SetCallback()

void OH_LOG_SetCallback(LogCallback callback)

Description

Registers a callback function. After this function is called, the custom callback can receive all HiLog logs of the current process.
Note that whether this API is called or not, it does not change the default log processing of the current process.

Since: 11

Parameters

Name	Description
LogCallback callback	Custom callback function. If processing of logs is not needed, a null pointer can be transferred.

OH_LOG_SetMinLogLevel()

void OH_LOG_SetMinLogLevel(LogLevel level)

Description

Sets the minimum log level.

NOTE

If the set log level is lower than the global log level, the setting does not take effect.
This function does not take effect for debug applications.

Since: 15

Parameters

Name	Description
LogLevel level	Log level.

OH_LOG_SetLogLevel()

void OH_LOG_SetLogLevel(LogLevel level, PreferStrategy prefer)

Description

Sets the minimum log level of the current application process.

You can configure different preference strategies using the prefer parameter. The PREFER_CLOSE_LOG strategy has the same effect as the OH_LOG_SetMinLogLevel() function.

Note: This function does not take effect for debug applications.

Since: 21

Parameters