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 "c4Base.h"
#include "c4Error.h"
#include "fleece/FLSlice.h"
#include <stdarg.h>
 
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;                              

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;

typedef struct C4LogEntry {
    C4Timestamp timestamp;
    C4LogLevel  level;
    C4LogDomain domain;
    FLHeapSlice message;
} C4LogEntry;

typedef struct C4DomainLevel {
    C4LogDomain domain;
    C4LogLevel  level;
} C4DomainLevel;

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

typedef struct C4LogObserverConfig {
    C4LogLevel                         defaultLevel;     
    const C4DomainLevel* C4NULLABLE    domains;          
    size_t                             domainsCount;     
    C4LogObserverCallback C4NULLABLE   callback;         
    void* C4NULLABLE                   callbackContext;  
    const C4LogFileOptions* C4NULLABLE fileOptions;      
} C4LogObserverConfig;
 
#pragma mark - LOG OBSERVERS:
 

CBL_CORE_API void c4log_initConsole(C4LogLevel) C4API;

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

CBL_CORE_API void c4log_removeObserver(C4LogObserver*) C4API;

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

CBL_CORE_API void c4logobserver_flush(C4LogObserver* observer) C4API;

CBL_CORE_API void c4log_consoleObserverCallback(const C4LogEntry*, void* C4NULLABLE context) 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 C4LogDomain c4log_nextDomain(C4LogDomain C4NULLABLE) 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__)
 
 
#pragma mark - LEGACY LOG FILE/CALLBACK API:
 

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;

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;

 
 
C4API_END_DECLS
C4_ASSUME_NONNULL_END