Logging

Data Structures
struct	C4LogFileOptions
	Configuration for file-based logging. More...
struct	C4LogEntry
	A log entry, as passed to a C4LogObserverCallback. More...
struct	C4DomainLevel
	A (domain, level) pair, used to customize a log observer's configuration. More...
struct	C4LogObserverConfig
	Configuration for creating a C4LogObserver, which may either call a callback or write to a file (but not both.) Exactly one of callback and fileOptions must be non-NULL. More...

Macros
#define	C4LogToAt(DOMAIN, LEVEL, FMT, ...)
#define	C4Debug(FMT, ...)
#define	C4Log(FMT, ...)
#define	C4LogVerbose(FMT, ...)
#define	C4Warn(FMT, ...)
#define	C4WarnError(FMT, ...)

Typedefs
typedef struct c4LogDomain *	C4LogDomain
	Reference to a log domain: a specific source of logs that can be enabled or disabled.
typedef void(*	C4LogObserverCallback) (const C4LogEntry *, void *context)
	The callback that will be called by a C4LogObserver.
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
CBL_CORE_API void	c4log_initConsole (C4LogLevel)
	Initializes logging by adding a default observer that writes to stderr, just like c4log_consoleObserverCallback.
NODISCARD CBL_CORE_API C4LogObserver *	c4log_newObserver (C4LogObserverConfig config, C4Error *outError)
	Creates and registers a log observer, returning a reference.
CBL_CORE_API void	c4log_removeObserver (C4LogObserver *)
	Unregisters a log observer.
NODISCARD CBL_CORE_API C4LogObserver *	c4log_replaceObserver (C4LogObserver *oldObs, C4LogObserverConfig config, C4Error *outError)
	Atomically unregisters an observer and registers a new one.
CBL_CORE_API void	c4logobserver_flush (C4LogObserver *observer)
	Ensures all log messages have been written to the observer's files.
CBL_CORE_API void	c4log_consoleObserverCallback (const C4LogEntry *, void *context)
	A C4LogObserverCallback that logs to stderr, or on Android to __android_log_write.
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 C4LogDomain	c4log_nextDomain (C4LogDomain)
	Returns the next log domain (in arbitrary order) after the given one; or the first domain if the argument is NULL.
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)
	Writes a preformatted message to log files, but does not invoke log callbacks.
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.

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,
			... )

Value:

C4LogToAt(kC4DefaultLog, kC4LogDebug, FMT, ##__VA_ARGS__)

C4Log

#define C4Log	(		FMT,
			... )

Value:

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,
			... )

Value:

C4LogToAt(kC4DefaultLog, kC4LogVerbose, FMT, ##__VA_ARGS__)

C4Warn

#define C4Warn	(		FMT,
			... )

Value:

C4LogToAt(kC4DefaultLog, kC4LogWarning, FMT, ##__VA_ARGS__)

C4WarnError

#define C4WarnError	(		FMT,
			... )

Value:

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.

C4LogObserverCallback

typedef void(* C4LogObserverCallback) (const C4LogEntry *, void *context)

The callback that will be called by a C4LogObserver.

Will be called on arbitrary threads. Should return as quickly as possible.

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_consoleObserverCallback()

CBL_CORE_API void c4log_consoleObserverCallback	(	const C4LogEntry *	,
		void *	context )

A C4LogObserverCallback that logs to stderr, or on Android to __android_log_write.

Note

The context argument is ignored.

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.

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_initConsole()

CBL_CORE_API void c4log_initConsole

(

C4LogLevel

)

Initializes logging by adding a default observer that writes to stderr, just like c4log_consoleObserverCallback.

You don't need to call this if you set up your own log observers.

c4log_newObserver()

NODISCARD CBL_CORE_API C4LogObserver * c4log_newObserver	(	C4LogObserverConfig	config,
		C4Error *	outError )

Creates and registers a log observer, returning a reference.

Fails if the configuration is invalid.

Note

Call c4logobserver_release when done with the reference. (You don't need to keep it unless you're going to call c4log_removeObserver later.)

c4log_nextDomain()

CBL_CORE_API C4LogDomain c4log_nextDomain

(

C4LogDomain

)

Returns the next log domain (in arbitrary order) after the given one; or the first domain if the argument is NULL.

You can iterate all domains like this: for(C4LogDomain d = c4log_nextDomain(NULL); d; d = c4log_nextDomain(d))

c4log_removeObserver()

CBL_CORE_API void c4log_removeObserver

(

C4LogObserver *

)

Unregisters a log observer.

Does nothing if it's not registered.

Note

This does not release your reference. You should call c4logobserver_release afterward if you don't need the object anymore.

c4log_replaceObserver()

NODISCARD CBL_CORE_API C4LogObserver * c4log_replaceObserver	(	C4LogObserver *	oldObs,
		C4LogObserverConfig	config,
		C4Error *	outError )

Atomically unregisters an observer and registers a new one.

If oldObs is NULL, nothing is unregistered. In case of failure (invalid config) oldObs is left intact and NULL is returned. It is possible that the observer is modified in place (the function retains & returns oldObs) but this should not affect your code's logic.

Note

Call c4logobserver_release when done with the returned reference.

This does not release oldObs. You should call c4logobserver_release afterward if you don't need the old observer anymore.

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.

c4logobserver_flush()

CBL_CORE_API void c4logobserver_flush

(

C4LogObserver *

observer

)

Ensures all log messages have been written to the observer's files.

If it's not a file-based observer, this is presently a no-op since callbacks are delivered synchronously.

c4slog()

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

Writes a preformatted message to log files, but does not invoke log callbacks.

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.