c4Log.h

Go to the documentation of this file.

//
// c4Log.h
//
// Copyright 2021-Present Couchbase, Inc.
//
// Use of this software is governed by the Business Source License included
// in the file licenses/BSL-Couchbase.txt.  As of the Change Date specified
// in that file, in accordance with the Business Source License, use of this
// software will be governed by the Apache License, Version 2.0, included in
// the file licenses/APL2.txt.
//
 
#pragma once
#include "c4Compat.h"
#include "c4Error.h"
#include "fleece/FLSlice.h"
#ifdef __cplusplus
#    include <cstdarg>
#else
#    include <stdarg.h>
#endif
 
C4_ASSUME_NONNULL_BEGIN
C4API_BEGIN_DECLS
 
 
/*
 * NOTE: All logging functions are thread-safe
 */
 
typedef C4_ENUM(int8_t, C4LogLevel){
        kC4LogDebug,    
        kC4LogVerbose,  
        kC4LogInfo,     
        kC4LogWarning,  
        kC4LogError,    
        kC4LogNone      
};
 
typedef struct c4LogDomain* C4LogDomain;
 
 
CBL_CORE_API extern const C4LogDomain kC4DefaultLog,  
        kC4DatabaseLog,                               
        kC4QueryLog,                                  
        kC4SyncLog,                                   
        kC4WebSocketLog;                              
 
 
#pragma mark - FILE LOGGING:
 
typedef struct C4LogFileOptions {
    C4LogLevel log_level;         
    FLString   base_path;         
    int64_t    max_size_bytes;    
    int32_t    max_rotate_count;  
    bool       use_plaintext;     
    FLString   header;            
} C4LogFileOptions;
 
NODISCARD CBL_CORE_API bool c4log_writeToBinaryFile(C4LogFileOptions options, C4Error* C4NULLABLE error) C4API;
 
CBL_CORE_API FLStringResult c4log_binaryFilePath(void) C4API;
 
CBL_CORE_API void c4log_flushLogFiles(void) C4API;
 
CBL_CORE_API C4LogLevel c4log_binaryFileLevel(void) C4API;
 
CBL_CORE_API void c4log_setBinaryFileLevel(C4LogLevel level) C4API;
 
 
#pragma mark - CALLBACK LOGGING:
 
 
typedef void (*C4NULLABLE C4LogCallback)(C4LogDomain, C4LogLevel, const char* fmt, va_list args);
 
CBL_CORE_API void c4log_writeToCallback(C4LogLevel level, C4LogCallback callback, bool preformatted) C4API;
 
CBL_CORE_API C4LogCallback c4log_getCallback(void) C4API;
 
CBL_CORE_API C4LogLevel c4log_callbackLevel(void) C4API;
 
CBL_CORE_API void c4log_setCallbackLevel(C4LogLevel level) C4API;
 
 
#pragma mark - LOG DOMAINS:
 
 
CBL_CORE_API C4LogDomain c4log_getDomain(const char* name, bool create) C4API;
 
CBL_CORE_API const char* c4log_getDomainName(C4LogDomain) C4API;
 
CBL_CORE_API C4LogLevel c4log_getLevel(C4LogDomain) C4API;
 
CBL_CORE_API bool c4log_willLog(C4LogDomain, C4LogLevel) C4API;
 
CBL_CORE_API void c4log_setLevel(C4LogDomain c4Domain, C4LogLevel level) C4API;
 
 
#pragma mark - LOGGING EXCEPTIONs:
 
 
CBL_CORE_API void c4log_warnOnErrors(bool) C4API;
 
CBL_CORE_API bool c4log_getWarnOnErrors(void) C4API;
 
CBL_CORE_API void c4log_enableFatalExceptionBacktrace(void) C4API;
 
 
#pragma mark - WRITING LOG MESSAGES:
 
 
CBL_CORE_API void c4log(C4LogDomain domain, C4LogLevel level, const char* fmt, ...) C4API __printflike(3, 4);
 
CBL_CORE_API void c4vlog(C4LogDomain domain, C4LogLevel level, const char* fmt, va_list args) C4API __printflike(3, 0);
 
CBL_CORE_API void c4slog(C4LogDomain domain, C4LogLevel level, FLString msg) C4API;
 
// Convenient aliases for c4log:
#define C4LogToAt(DOMAIN, LEVEL, FMT, ...)                                                                             \
    do {                                                                                                               \
        if ( c4log_willLog(DOMAIN, LEVEL) ) c4log(DOMAIN, LEVEL, FMT, ##__VA_ARGS__);                                  \
    } while ( false )
#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__)
 
 
C4API_END_DECLS
C4_ASSUME_NONNULL_END