Aerospike C 客戶端日誌系統：級別控制與自訂回調完整指南

日誌架構概覽

Aerospike C 客戶端內建日誌設施，預設輸出至 stderr。應用可：

1. 調整日誌詳細程度
2. 註冊自訂回調函數，實現重導向、過濾、格式化、結構化日誌（JSON）、整合既有日誌框架

日誌級別設定

// 3.0.86+ 版本
as_log_set_level(AS_LOG_LEVEL_DEBUG);

// 3.0.85 及舊版本
as_log_set_level(&as->log, AS_LOG_LEVEL_DEBUG);

級別常數（由低到高）

自訂日誌回調函數

函數原型

typedef bool (*as_log_callback)(as_log_level level, const char *func, 
                                const char *file, uint32_t line, 
                                const char *fmt, ...);

參數說明

• level：日誌級別
• func：記錄日誌的函數名
• file：原始碼檔案名
• line：行號
• fmt + 可變參數：格式化字串
• 回傳 true 表示處理完成，false 可能影響內部邏輯

範例：格式化輸出至 stderr

bool my_log_callback(as_log_level level, const char *func, 
                     const char *file, uint32_t line, 
                     const char *fmt, ...) {
    char msg[1024] = {0};
    va_list ap;
    va_start(ap, fmt);
    vsnprintf(msg, sizeof(msg), fmt, ap);
    msg[sizeof(msg)-1] = '\0';
    va_end(ap);

    // 格式：[檔案:行號][函數] 級別 - 訊息
    fprintf(stderr, "[%s:%d][%s] %d - %s\n", file, line, func, level, msg);
    return true;
}

註冊回調

// 3.0.86+
as_log_set_level(AS_LOG_LEVEL_INFO);
as_log_set_callback(my_log_callback);

// 3.0.85 舊版
as_log_set_level(&as->log, AS_LOG_LEVEL_INFO);
as_log_set_callback(&as->log, my_log_callback);

進階應用場景

整合 syslog / log4c / spdlog

bool syslog_callback(as_log_level level, const char *func, 
                     const char *file, uint32_t line, 
                     const char *fmt, ...) {
    char msg[2048];
    va_list ap;
    va_start(ap, fmt);
    vsnprintf(msg, sizeof(msg), fmt, ap);
    va_end(ap);

    int syslog_level;
    switch (level) {
        case AS_LOG_LEVEL_ERROR: syslog_level = LOG_ERR; break;
        case AS_LOG_LEVEL_WARN:  syslog_level = LOG_WARNING; break;
        case AS_LOG_LEVEL_INFO:  syslog_level = LOG_INFO; break;
        case AS_LOG_LEVEL_DEBUG: syslog_level = LOG_DEBUG; break;
        default: syslog_level = LOG_NOTICE;
    }
    syslog(syslog_level, "[%s:%d][%s] %s", file, line, func, msg);
    return true;
}

結構化 JSON 日誌（ELK/Graylog 友善）

bool json_callback(as_log_level level, const char *func, 
                   const char *file, uint32_t line, 
                   const char *fmt, ...) {
    char msg[1024];
    va_list ap;
    va_start(ap, fmt);
    vsnprintf(msg, sizeof(msg), fmt, ap);
    va_end(ap);

    // 簡易 JSON，生產建議使用 cJSON/rapidjson
    time_t now = time(NULL);
    struct tm *tm = gmtime(&now);
    char timestamp[32];
    strftime(timestamp, sizeof(timestamp), "%Y-%m-%dT%H:%M:%SZ", tm);

    fprintf(stderr, 
        "{\"timestamp\":\"%s\",\"level\":%d,\"file\":\"%s\",\"line\":%u,\"func\":\"%s\",\"msg\":\"%s\"}\n",
        timestamp, level, file, line, func, msg);
    return true;
}

版本相容性提醒

• 3.0.86+：全域函數 as_log_set_level()、as_log_set_callback()
• ≤ 3.0.85：需透過 client 物件 &as->log 傳遞
• 升級時注意 API 變更，建議封裝成專案統一的日誌初始化模組

效能考量

• 生產環境建議 INFO 或 WARN 級別
• 避免回調中進行阻塞 I/O（同步寫檔、網路發送），改用非同步日誌庫
• 高頻操作路徑（如熱鍵讀寫）若啟用 DEBUG/TRACE 會顯著影響延遲