spdlog Configuration Options in tweakme.h: Complete Compile-Time Customization Guide

spdlog configuration options in tweakme.h allow you to customize logging behavior at compile time by uncommenting macros in include/spdlog/tweakme.h, enabling optimizations like zero-cost filtering, coarse clocks, and external fmt library integration.

spdlog is a header-only C++ logging library that achieves zero-overhead abstraction through compile-time configuration. The spdlog configuration options in tweakme.h provide a centralized mechanism to tailor performance characteristics, output formats, and platform-specific behaviors without runtime penalties. Located in include/spdlog/tweakme.h, this file is automatically included by include/spdlog/common.h and processed during the pre-processor phase, ensuring only required code paths exist in your final binary.

Understanding tweakme.h Structure

The include/spdlog/tweakme.h file serves as the central configuration hub for the spdlog library. Unlike runtime configuration methods, these settings take effect during compilation, eliminating unnecessary overhead.

The file contains commented-out macro definitions that you uncomment to enable specific behaviors. Because include/spdlog/common.h includes this file early in the compilation process, these definitions propagate throughout the library, affecting components in src/spdlog.cpp, src/async.cpp, and src/file_sinks.cpp.

Performance Optimization Macros

Clock Source Selection (SPDLOG_CLOCK_COARSE)

On Linux systems, uncomment SPDLOG_CLOCK_COARSE to use CLOCK_REALTIME_COARSE instead of the standard clock. This trades nanosecond precision for faster system calls, reducing latency in high-frequency logging scenarios.

Eliminating Source Location Overhead (SPDLOG_NO_SOURCE_LOC)

When you define SPDLOG_NO_SOURCE_LOC, spdlog strips __FILE__, __LINE__, and SPDLOG_FUNCTION from log records. This reduces binary size and eliminates the overhead of capturing source locations, particularly beneficial in production builds where stack traces are handled externally.

// In include/spdlog/tweakme.h
#define SPDLOG_NO_SOURCE_LOC

// In your application
#include <spdlog/spdlog.h>

int main() {
    spdlog::info("No __FILE__/__LINE__ info attached");
}

Threading Optimizations

• SPDLOG_NO_THREAD_ID: Disables thread-ID lookup for the %t pattern placeholder. When enabled, %t resolves to 0, eliminating thread-local storage lookups.
• SPDLOG_NO_TLS: Prevents thread-local storage usage for loggers. Essential when your application forks processes, as child processes inherit undefined thread IDs from parents.
• SPDLOG_NO_ATOMIC_LEVELS: Removes atomic operations on logger levels. Only safe when log levels remain static after initialization, removing memory barriers in hot paths.

Content and Format Customization

Custom Level Names (SPDLOG_LEVEL_NAMES and SPDLOG_SHORT_LEVEL_NAMES)

Redefine how severity levels appear in output:

// In include/spdlog/tweakme.h
#define SPDLOG_LEVEL_NAMES { "TRC", "DBG", "INF", "WRN", "ERR", "CRT", "OFF" }
#define SPDLOG_SHORT_LEVEL_NAMES { "T", "D", "I", "W", "E", "C", "O" }

// In your application
#include <spdlog/spdlog.h>

int main() {
    spdlog::warn("This prints WRN instead of warning");
}

These arrays map directly to spdlog's level enum (trace, debug, info, warning, error, critical, off).

Line Endings and Path Separators

• SPDLOG_EOL: Override the default newline sequence ("\n" on Linux, "\r\n" on Windows).
• SPDLOG_FOLDER_SEPS: Define custom characters recognized as folder separators for file sink path handling.
• SPDLOG_FUNCTION: Override the function name macro (default is __FUNCTION__ or __PRETTY_FUNCTION__ depending on compiler).

Platform-Specific Configuration

Windows Character Encoding

• SPDLOG_WCHAR_FILENAMES: Enables wchar_t support for file sink paths on Windows.
• SPDLOG_WCHAR_TO_UTF8_SUPPORT: Automatically converts wide-character log messages to UTF-8 encoding.

File Descriptor Handling (SPDLOG_PREVENT_CHILD_FD)

Define SPDLOG_PREVENT_CHILD_FD to set O_CLOEXEC or equivalent flags on log file descriptors. This prevents child processes spawned via fork()/exec() from inheriting open log files, avoiding duplicate writes and file corruption in multi-process architectures.

// In include/spdlog/tweakme.h
#define SPDLOG_PREVENT_CHILD_FD

#include <spdlog/sinks/basic_file_sink.h>
#include <unistd.h>

int main() {
    auto logger = spdlog::basic_logger_mt("file_logger", "app.log");
    pid_t pid = fork();
    if (pid == 0) { 
        /* child process - file descriptor is automatically closed */ 
        execvp("ls", nullptr); 
    }
}

Third-Party Integration

External Formatting Libraries

• SPDLOG_FMT_EXTERNAL: Links against an external fmt library instead of the bundled version. Requires adding -I<path/to/fmt/include> to your build flags and linking against fmt.
• SPDLOG_USE_STD_FORMAT: Switches to C++20 std::format, removing the fmt dependency entirely (requires C++20 compliant compiler).

// In include/spdlog/tweakme.h
#define SPDLOG_FMT_EXTERNAL

// Build with: -I/path/to/fmt/include
#include <spdlog/spdlog.h>

int main() {
    spdlog::info("Formatted number: {}", 42);
}

Default Logger Control

SPDLOG_DISABLE_DEFAULT_LOGGER skips creation of the implicit global logger in src/spdlog.cpp. Use this in embedded systems or when you explicitly manage all logger instances to save initialization time and memory.

Compile-Time Level Filtering

The SPDLOG_ACTIVE_LEVEL macro provides zero-cost log level filtering. Unlike runtime set_level() calls, this macro causes logging macros below the specified level to compile to no-ops.

// In include/spdlog/tweakme.h
#define SPDLOG_ACTIVE_LEVEL SPDLOG_LEVEL_INFO

// In your application
#include <spdlog/spdlog.h>

int main() {
    spdlog::debug("This call generates zero machine code");  // Eliminated at compile time
    spdlog::info("Application started");                     // Executed
}

Available levels: SPDLOG_LEVEL_TRACE, SPDLOG_LEVEL_DEBUG, SPDLOG_LEVEL_INFO, SPDLOG_LEVEL_WARN, SPDLOG_LEVEL_ERROR, SPDLOG_LEVEL_CRITICAL, SPDLOG_LEVEL_OFF.

Practical Configuration Examples

High-Performance Server Configuration

For production servers requiring minimal latency:

// In include/spdlog/tweakme.h
#define SPDLOG_CLOCK_COARSE
#define SPDLOG_NO_SOURCE_LOC
#define SPDLOG_NO_THREAD_ID
#define SPDLOG_ACTIVE_LEVEL SPDLOG_LEVEL_INFO

Fork-Safe Daemon Configuration

// In include/spdlog/tweakme.h
#define SPDLOG_NO_TLS
#define SPDLOG_PREVENT_CHILD_FD

Summary

• spdlog configuration options in tweakme.h reside in include/spdlog/tweakme.h and are included automatically by include/spdlog/common.h.
• These macros operate at compile time, eliminating runtime overhead for disabled features.
• SPDLOG_ACTIVE_LEVEL provides zero-cost filtering by compiling out log statements below the specified level.
• Performance options like SPDLOG_CLOCK_COARSE, SPDLOG_NO_SOURCE_LOC, and SPDLOG_NO_ATOMIC_LEVELS minimize latency in high-frequency logging scenarios.
• Platform-specific macros such as SPDLOG_WCHAR_FILENAMES and SPDLOG_PREVENT_CHILD_FD handle operating system differences.
• Integration macros SPDLOG_FMT_EXTERNAL and SPDLOG_USE_STD_FORMAT allow switching between bundled fmt, external fmt, or C++20 std::format.

Frequently Asked Questions

What is tweakme.h in spdlog?

The include/spdlog/tweakme.h file is the central compile-time configuration header for the spdlog library. It contains commented-out macro definitions that you uncomment to enable specific optimizations, customizations, and platform-specific behaviors. Because these settings are processed by the pre-processor before compilation, they create zero runtime overhead for features you disable.

How do I use an external fmt library with spdlog?

Uncomment SPDLOG_FMT_EXTERNAL in include/spdlog/tweakme.h and ensure your build system includes the path to your fmt installation with -I<path/to/fmt/include> and links against the fmt library. This configuration forces spdlog to use your system's fmt headers instead of the bundled version in include/spdlog/fmt/.

What is the difference between SPDLOG_ACTIVE_LEVEL and set_level()?

SPDLOG_ACTIVE_LEVEL is a compile-time filter defined in tweakme.h that causes logging macros below the specified level to compile into no-operations, completely removing them from the binary. In contrast, logger->set_level() is a runtime method that checks the level during execution and can be changed dynamically. Use SPDLOG_ACTIVE_LEVEL for zero-cost filtering in performance-critical paths where levels won't change.

How do I prevent child processes from inheriting log file descriptors?

Define SPDLOG_PREVENT_CHILD_FD in include/spdlog/tweakme.h. This macro ensures that file sinks in src/file_sinks.cpp open files with O_CLOEXEC (or equivalent flags), preventing file descriptor inheritance across fork() and exec() calls. This is essential for daemon processes that spawn child processes to avoid duplicate log entries and file corruption.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}