Logging

Data Structures
struct	C4LogFileOptions
	Configuration for file-based logging. More...

Macros
#define	C4LogToAt(DOMAIN, LEVEL, FMT, ...)
#define	C4Debug(FMT, ...)   C4LogToAt(kC4DefaultLog, kC4LogDebug, FMT, ##__VA_ARGS__)
#define	C4Log(FMT, ...)   C4LogToAt(kC4DefaultLog, kC4LogInfo, FMT, ##__VA_ARGS__)
#define	C4LogVerbose(FMT, ...)   C4LogToAt(kC4DefaultLog, kC4LogVerbose, FMT, ##__VA_ARGS__)
#define	C4Warn(FMT, ...)   C4LogToAt(kC4DefaultLog, kC4LogWarning, FMT, ##__VA_ARGS__)
#define	C4WarnError(FMT, ...)   C4LogToAt(kC4DefaultLog, kC4LogError, FMT, ##__VA_ARGS__)

Typedefs
typedef struct c4LogDomain *	C4LogDomain
	Reference to a log domain: a specific source of logs that can be enabled or disabled.
typedef void(*	C4LogCallback) (C4LogDomain, C4LogLevel, const char *fmt, va_list args)
	A logging callback that the application can register.

Enumerations
enum	C4LogLevel : int8_t {   kC4LogDebug , kC4LogVerbose , kC4LogInfo , kC4LogWarning ,   kC4LogError , kC4LogNone }

Functions
NODISCARD CBL_CORE_API bool	c4log_writeToBinaryFile (C4LogFileOptions options, C4Error *error)
	Causes log messages to be written to a file, overwriting any previous contents.
CBL_CORE_API FLStringResult	c4log_binaryFilePath (void)
	Returns the filesystem path of the directory where log files are kept.
CBL_CORE_API void	c4log_flushLogFiles (void)
	Ensures all log messages have been written to the current log files.
CBL_CORE_API C4LogLevel	c4log_binaryFileLevel (void)
	Returns the minimum level of log messages to be written to the log file, regardless of what level individual log domains are set to.
CBL_CORE_API void	c4log_setBinaryFileLevel (C4LogLevel level)
	Sets the minimum level of log messages to be written to the log file.
CBL_CORE_API void	c4log_writeToCallback (C4LogLevel level, C4LogCallback callback, bool preformatted)
	Registers (or unregisters) a log callback, and sets the minimum log level to report.
CBL_CORE_API C4LogCallback	c4log_getCallback (void)
	Returns the current logging callback, or the default one if none has been set.
CBL_CORE_API C4LogLevel	c4log_callbackLevel (void)
	Returns the minimum level of log messages to be reported via callback, regardless of what level individual log domains are set to.
CBL_CORE_API void	c4log_setCallbackLevel (C4LogLevel level)
	Sets the minimum level of log messages to be reported via callback.
CBL_CORE_API C4LogDomain	c4log_getDomain (const char *name, bool create)
	Looks up a named log domain.
CBL_CORE_API const char *	c4log_getDomainName (C4LogDomain)
	Returns the name of a log domain.
CBL_CORE_API C4LogLevel	c4log_getLevel (C4LogDomain)
	Returns the current log level of a domain, the minimum level of message it will log.
CBL_CORE_API bool	c4log_willLog (C4LogDomain, C4LogLevel)
	Returns true if logging to this domain at this level will have an effect.
CBL_CORE_API void	c4log_setLevel (C4LogDomain c4Domain, C4LogLevel level)
	Changes the level of the given log domain.
CBL_CORE_API void	c4log_warnOnErrors (bool)
	If set to true, LiteCore will log a warning of the form "LiteCore throwing %s error %d: %s" just before throwing an internal exception.
CBL_CORE_API bool	c4log_getWarnOnErrors (void)
	Returns true if warn-on-errors is on; see c4log_warnOnErrors.
CBL_CORE_API void	c4log_enableFatalExceptionBacktrace (void)
	Registers a handler with the C++ runtime that will log a backtrace when an uncaught C++ exception occurs, just before the process aborts.
CBL_CORE_API void	c4log (C4LogDomain domain, C4LogLevel level, const char *fmt,...) __printflike(3
	Logs a message/warning/error to a specific domain, if its current level is less than or equal to the given level.
CBL_CORE_API void CBL_CORE_API void	c4vlog (C4LogDomain domain, C4LogLevel level, const char *fmt, va_list args) __printflike(3
	Same as c4log, for use in calling functions that already take variable args.
CBL_CORE_API void CBL_CORE_API void CBL_CORE_API void	c4slog (C4LogDomain domain, C4LogLevel level, FLString msg)
	Same as c4log, except it accepts preformatted messages as FLSlices.

Variables
CBL_CORE_API const C4LogDomain	kC4DefaultLog
	Subsystems that produce logs.
CBL_CORE_API const C4LogDomain	kC4DatabaseLog
	Log domain for database operations.
CBL_CORE_API const C4LogDomain	kC4QueryLog
	Log domain for query operations.
CBL_CORE_API const C4LogDomain	kC4SyncLog
	Log domain for replication operations.
CBL_CORE_API const C4LogDomain	kC4WebSocketLog
	Log domain for WebSocket operations.

Detailed Description

Macro Definition Documentation

C4Debug

#define C4Debug	(		FMT,
			...
	)		C4LogToAt(kC4DefaultLog, kC4LogDebug, FMT, ##__VA_ARGS__)

C4Log

#define C4Log	(		FMT,
			...
	)		C4LogToAt(kC4DefaultLog, kC4LogInfo, FMT, ##__VA_ARGS__)

C4LogToAt

#define C4LogToAt	(		DOMAIN,
			LEVEL,
			FMT,
			...
	)

Value:

    do {                                                                                                               \
        if ( c4log_willLog(DOMAIN, LEVEL) ) c4log(DOMAIN, LEVEL, FMT, ##__VA_ARGS__);                                  \
    } while ( false )

C4LogVerbose

#define C4LogVerbose	(		FMT,
			...
	)		C4LogToAt(kC4DefaultLog, kC4LogVerbose, FMT, ##__VA_ARGS__)

C4Warn

#define C4Warn	(		FMT,
			...
	)		C4LogToAt(kC4DefaultLog, kC4LogWarning, FMT, ##__VA_ARGS__)

C4WarnError

#define C4WarnError	(		FMT,
			...
	)		C4LogToAt(kC4DefaultLog, kC4LogError, FMT, ##__VA_ARGS__)

Typedef Documentation

C4LogCallback

typedef void(* C4LogCallback) (C4LogDomain, C4LogLevel, const char *fmt, va_list args)

A logging callback that the application can register.

C4LogDomain

typedef struct c4LogDomain* C4LogDomain

Reference to a log domain: a specific source of logs that can be enabled or disabled.

Enumeration Type Documentation

C4LogLevel

enum C4LogLevel : int8_t

Enumerator
kC4LogDebug
kC4LogVerbose	Super-verbose messages that are only enabled in debug builds of LiteCore.
kC4LogInfo	More info than you normally want.
kC4LogWarning	Informational messages.
kC4LogError	Warnings about something unusual that might be a problem.
kC4LogNone	Errors that occur; these might be handled internally. Setting this level will disable logging entirely

Function Documentation

c4log()

CBL_CORE_API void c4log	(	C4LogDomain	domain,
		C4LogLevel	level,
		const char *	fmt,
			...
	)

Logs a message/warning/error to a specific domain, if its current level is less than or equal to the given level.

This message will then be written to the current callback and/or binary file, if their levels are less than or equal to the given level.

Parameters

domain	The domain to log to.
level	The level of the message. If the domain's level is greater than this, nothing will be logged.
fmt	printf-style format string, followed by arguments (if any).

c4log_binaryFileLevel()

CBL_CORE_API C4LogLevel c4log_binaryFileLevel

(

void

)

Returns the minimum level of log messages to be written to the log file, regardless of what level individual log domains are set to.

c4log_binaryFilePath()

CBL_CORE_API FLStringResult c4log_binaryFilePath

(

void

)

Returns the filesystem path of the directory where log files are kept.

c4log_callbackLevel()

CBL_CORE_API C4LogLevel c4log_callbackLevel

(

void

)

Returns the minimum level of log messages to be reported via callback, regardless of what level individual log domains are set to.

c4log_enableFatalExceptionBacktrace()

CBL_CORE_API void c4log_enableFatalExceptionBacktrace

(

void

)

Registers a handler with the C++ runtime that will log a backtrace when an uncaught C++ exception occurs, just before the process aborts.

c4log_flushLogFiles()

CBL_CORE_API void c4log_flushLogFiles

(

void

)

Ensures all log messages have been written to the current log files.

c4log_getCallback()

CBL_CORE_API C4LogCallback c4log_getCallback

(

void

)

Returns the current logging callback, or the default one if none has been set.

c4log_getDomain()

CBL_CORE_API C4LogDomain c4log_getDomain	(	const char *	name,
		bool	create
	)

Looks up a named log domain.

Parameters

name	The name of the domain, or NULL for the default domain.
create	If true, the domain will be created if it doesn't exist.

Returns

The domain object, or NULL if not found.

c4log_getDomainName()

CBL_CORE_API const char * c4log_getDomainName

(

C4LogDomain

)

Returns the name of a log domain.

(The default domain's name is an empty string.)

c4log_getLevel()

CBL_CORE_API C4LogLevel c4log_getLevel

(

C4LogDomain

)

Returns the current log level of a domain, the minimum level of message it will log.

c4log_getWarnOnErrors()

CBL_CORE_API bool c4log_getWarnOnErrors

(

void

)

Returns true if warn-on-errors is on; see c4log_warnOnErrors.

Default is false.

c4log_setBinaryFileLevel()

CBL_CORE_API void c4log_setBinaryFileLevel

(

C4LogLevel

level

)

Sets the minimum level of log messages to be written to the log file.

c4log_setCallbackLevel()

CBL_CORE_API void c4log_setCallbackLevel

(

C4LogLevel

level

)

Sets the minimum level of log messages to be reported via callback.

c4log_setLevel()

CBL_CORE_API void c4log_setLevel	(	C4LogDomain	c4Domain,
		C4LogLevel	level
	)

Changes the level of the given log domain.

This setting is global to the entire process. Logging is further limited by the levels assigned to the current callback and/or binary file. For example, if you set the Foo domain's level to Verbose, and the current log callback is at level Warning while the binary file is at Verbose, then verbose Foo log messages will be written to the file but not to the callback.

c4log_warnOnErrors()

CBL_CORE_API void c4log_warnOnErrors

(

bool

)

If set to true, LiteCore will log a warning of the form "LiteCore throwing %s error %d: %s" just before throwing an internal exception.

This can be a good way to catch the source where an error occurs.

c4log_willLog()

CBL_CORE_API bool c4log_willLog	(	C4LogDomain	,
		C4LogLevel
	)

Returns true if logging to this domain at this level will have an effect.

This is called by the C4Log macros (below), to skip the possibly-expensive evaluation of parameters if nothing will be logged anyway. (This is not the same as comparing c4log_getLevel, because even if the domain's level indicates it would log, logging could still be suppressed by the global callbackLevel or binaryFileLevel.)

c4log_writeToBinaryFile()

NODISCARD CBL_CORE_API bool c4log_writeToBinaryFile	(	C4LogFileOptions	options,
		C4Error *	error
	)

Causes log messages to be written to a file, overwriting any previous contents.

The data is written in an efficient and compact binary form that can be read using the "litecorelog" tool.

Parameters

options	The options to use when setting up the binary logger
error	On failure, the filesystem error that caused the call to fail.

Returns

True on success, false on failure.

c4log_writeToCallback()

CBL_CORE_API void c4log_writeToCallback	(	C4LogLevel	level,
		C4LogCallback	callback,
		bool	preformatted
	)

Registers (or unregisters) a log callback, and sets the minimum log level to report.

Before this is called, a default callback is used that writes to stderr at the Info level. NOTE: this setting is global to the entire process.

Parameters

level	The minimum level of message to log.
callback	The logging callback, or NULL to disable logging entirely.
preformatted	If true, log messages will be formatted before invoking the callback, so the fmt parameter will be the actual string to log, and the args parameter will be NULL.

c4slog()

CBL_CORE_API void CBL_CORE_API void CBL_CORE_API void c4slog	(	C4LogDomain	domain,
		C4LogLevel	level,
		FLString	msg
	)

Same as c4log, except it accepts preformatted messages as FLSlices.

c4vlog()

CBL_CORE_API void CBL_CORE_API void c4vlog	(	C4LogDomain	domain,
		C4LogLevel	level,
		const char *	fmt,
		va_list	args
	)

Same as c4log, for use in calling functions that already take variable args.

Variable Documentation

kC4DatabaseLog

CBL_CORE_API const C4LogDomain kC4DatabaseLog

Log domain for database operations.

kC4DefaultLog

CBL_CORE_API const C4LogDomain kC4DefaultLog

extern

Subsystems that produce logs.

Log levels can be configured for each, so you can focus your diagnostic efforts on the area of interest. The default log domain

kC4QueryLog

CBL_CORE_API const C4LogDomain kC4QueryLog

Log domain for query operations.

kC4SyncLog

CBL_CORE_API const C4LogDomain kC4SyncLog

Log domain for replication operations.

kC4WebSocketLog

CBL_CORE_API const C4LogDomain kC4WebSocketLog

Log domain for WebSocket operations.