kcenon::logger::logfmt_formatter Class Reference

Formatter that outputs logfmt-structured log messages. More...

#include <logfmt_formatter.h>

Inheritance diagram for kcenon::logger::logfmt_formatter:

Collaboration diagram for kcenon::logger::logfmt_formatter:

Public Member Functions
	logfmt_formatter (const format_options &opts=format_options{})
	Constructor with optional format options.
std::string	format (const log_entry &entry) const override
	Format a log entry to logfmt string.
std::string	get_name () const override
	Get formatter name.
Public Member Functions inherited from kcenon::logger::log_formatter_interface
virtual	~log_formatter_interface ()=default
virtual void	set_options (const format_options &opts)
	Set formatting options.
virtual format_options	get_options () const
	Get current formatting options.

Static Private Member Functions
static std::string	level_to_lowercase (log_level level)
	Convert log level to lowercase string.
static std::string	escape_logfmt_key (const std::string &key)
	Escape a logfmt key (remove spaces and special characters)
static std::string	escape_logfmt_value (const std::string &value)
	Escape a logfmt value.
static void	format_value (std::ostringstream &oss, const log_value &value)
	Format a log_value to logfmt.

Additional Inherited Members
Protected Attributes inherited from kcenon::logger::log_formatter_interface
format_options	options_

Detailed Description

Formatter that outputs logfmt-structured log messages.

Produces machine-readable logfmt output suitable for log aggregation, analysis tools, and automated processing. The format consists of key=value pairs separated by spaces.

Features:

• ISO 8601 timestamp format (RFC 3339)
• Proper escaping of special characters
• Structured source location information
• OpenTelemetry context support (trace_id, span_id)
• Compatible with logfmt parsers and log aggregation systems

Thread-safety: This formatter is stateless and thread-safe.

Since

3.1.0

Examples

structured_logging_example.cpp.

Definition at line 68 of file logfmt_formatter.h.

Constructor & Destructor Documentation

logfmt_formatter()

kcenon::logger::logfmt_formatter::logfmt_formatter ( const format_options & opts = format_options{} )

inlineexplicit

Constructor with optional format options.

Parameters

opts	Initial format options

Note

For logfmt output, use_colors and pretty_print options are ignored

Since

3.1.0

Definition at line 78 of file logfmt_formatter.h.

                                                                         {}) {
        options_ = opts;
        // Logfmt doesn't support colors or pretty print
        options_.use_colors = false;
        options_.pretty_print = false;
    }

Member Function Documentation

escape_logfmt_key()

static std::string kcenon::logger::logfmt_formatter::escape_logfmt_key ( const std::string & key )

inlinestaticprivate

Escape a logfmt key (remove spaces and special characters)

Parameters

key	Key to escape

Returns

Escaped key

Definition at line 217 of file logfmt_formatter.h.

                                                             {
        std::string result;
        result.reserve(key.size());
        for (char c : key) {
            if (c == ' ' || c == '=' || c == '"' || c == '\n' || c == '\t') {
                result += '_';
            } else {
                result += c;
            }
        }
        return result;
    }

Referenced by format().

Here is the caller graph for this function:

escape_logfmt_value()

static std::string kcenon::logger::logfmt_formatter::escape_logfmt_value ( const std::string & value )

inlinestaticprivate

Escape a logfmt value.

Parameters

value

Value to escape

Returns

Escaped value (quoted if necessary)

Values containing spaces, quotes, or special characters are wrapped in double quotes with proper escaping.

Definition at line 238 of file logfmt_formatter.h.

                                                                 {
        // Check if quoting is needed
        bool needs_quoting = false;
        for (char c : value) {
            if (c == ' ' || c == '"' || c == '=' || c == '\n' || c == '\t' || c == '\r') {
                needs_quoting = true;
                break;
            }
        }
 
        if (!needs_quoting && !value.empty()) {
            return value;
        }
 
        // Quote and escape
        std::ostringstream oss;
        oss << '"';
        for (char c : value) {
            switch (c) {
                case '"': oss << "\\\""; break;
                case '\\': oss << "\\\\"; break;
                case '\n': oss << "\\n"; break;
                case '\r': oss << "\\r"; break;
                case '\t': oss << "\\t"; break;
                default: oss << c;
            }
        }
        oss << '"';
        return oss.str();
    }

Referenced by format(), and format_value().

Here is the caller graph for this function:

format()

std::string kcenon::logger::logfmt_formatter::format ( const log_entry & entry ) const

inlinenodiscardoverridevirtual

Format a log entry to logfmt string.

Parameters

entry

The log entry to format

Returns

Logfmt-formatted string

Produces key=value pairs with fields:

• level: Log level as lowercase string
• ts: ISO 8601 format timestamp (UTC)
• msg: Log message (escaped)
• thread_id: Thread ID
• file, line, function: Source location (if enabled)
• trace_id, span_id: OpenTelemetry context (if present)
• Additional structured fields

Note

Thread-safe. Can be called concurrently.

Since

3.1.0

Implements kcenon::logger::log_formatter_interface.

Examples

structured_logging_example.cpp.

Definition at line 103 of file logfmt_formatter.h.

                                                                          {
        std::ostringstream oss;
        bool first = true;
 
        // Level
        if (options_.include_level) {
            oss << "level=" << level_to_lowercase(entry.level);
            first = false;
        }
 
        // Timestamp (ISO 8601)
        if (options_.include_timestamp) {
            if (!first) {
                oss << " ";
            }
            oss << "ts=" << utils::time_utils::format_iso8601(entry.timestamp);
            first = false;
        }
 
        // Message (always include)
        if (!first) {
            oss << " ";
        }
        oss << "msg=" << escape_logfmt_value(entry.message.to_string());
        first = false;
 
        // Thread ID
        if (options_.include_thread_id && entry.thread_id) {
            oss << " thread_id=" << escape_logfmt_value(entry.thread_id->to_string());
        }
 
        // Source location
        if (options_.include_source_location && entry.location) {
            std::string file_path = entry.location->file.to_string();
            if (!file_path.empty()) {
                oss << " file=" << escape_logfmt_value(file_path);
            }
 
            if (entry.location->line > 0) {
                oss << " line=" << entry.location->line;
            }
 
            std::string func = entry.location->function.to_string();
            if (!func.empty()) {
                oss << " function=" << escape_logfmt_value(func);
            }
        }
 
        // Category (if present)
        if (entry.category) {
            std::string cat = entry.category->to_string();
            if (!cat.empty()) {
                oss << " category=" << escape_logfmt_value(cat);
            }
        }
 
        // OpenTelemetry context (if present)
        if (entry.otel_ctx && entry.otel_ctx->is_valid()) {
            if (!entry.otel_ctx->trace_id.empty()) {
                oss << " trace_id=" << entry.otel_ctx->trace_id;
            }
            if (!entry.otel_ctx->span_id.empty()) {
                oss << " span_id=" << entry.otel_ctx->span_id;
            }
            if (!entry.otel_ctx->trace_flags.empty()) {
                oss << " trace_flags=" << entry.otel_ctx->trace_flags;
            }
        }
 
        // Structured fields (if present)
        if (entry.fields && !entry.fields->empty()) {
            for (const auto& [key, value] : *entry.fields) {
                oss << " " << escape_logfmt_key(key) << "=";
                format_value(oss, value);
            }
        }
 
        return oss.str();
    }

References kcenon::logger::log_entry::category, escape_logfmt_key(), escape_logfmt_value(), kcenon::logger::log_entry::fields, kcenon::logger::utils::time_utils::format_iso8601(), format_value(), kcenon::logger::format_options::include_level, kcenon::logger::format_options::include_source_location, kcenon::logger::format_options::include_thread_id, kcenon::logger::format_options::include_timestamp, kcenon::logger::log_entry::level, level_to_lowercase(), kcenon::logger::log_entry::location, kcenon::logger::log_entry::message, kcenon::logger::log_formatter_interface::options_, kcenon::logger::log_entry::otel_ctx, kcenon::logger::log_entry::thread_id, kcenon::logger::log_entry::timestamp, and kcenon::logger::small_string< SSO_SIZE >::to_string().

Referenced by logfmt_formatter_example().

Here is the call graph for this function:

Here is the caller graph for this function:

format_value()

static void kcenon::logger::logfmt_formatter::format_value ( std::ostringstream & oss, const log_value & value )

inlinestaticprivate

Format a log_value to logfmt.

Parameters

oss	Output stream
value	Value to format

Definition at line 274 of file logfmt_formatter.h.

                                                                            {
        std::visit([&oss](const auto& v) {
            using T = std::decay_t<decltype(v)>;
            if constexpr (std::is_same_v<T, std::string>) {
                oss << escape_logfmt_value(v);
            } else if constexpr (std::is_same_v<T, bool>) {
                oss << (v ? "true" : "false");
            } else if constexpr (std::is_same_v<T, int64_t>) {
                oss << v;
            } else if constexpr (std::is_same_v<T, double>) {
                oss << std::fixed << std::setprecision(6) << v;
            } else {
                oss << v;
            }
        }, value);
    }

References escape_logfmt_value().

Referenced by format().

Here is the call graph for this function:

Here is the caller graph for this function:

get_name()

std::string kcenon::logger::logfmt_formatter::get_name ( ) const

inlinenodiscardoverridevirtual

Get formatter name.

Returns

"logfmt_formatter"

Since

3.1.0

Implements kcenon::logger::log_formatter_interface.

Definition at line 189 of file logfmt_formatter.h.

                                                      {
        return "logfmt_formatter";
    }

level_to_lowercase()

static std::string kcenon::logger::logfmt_formatter::level_to_lowercase ( log_level level )

inlinestaticprivate

Convert log level to lowercase string.

Parameters

level

Log level

Returns

Lowercase string representation

Definition at line 199 of file logfmt_formatter.h.

                                                         {
        switch (level) {
            case log_level::trace: return "trace";
            case log_level::debug: return "debug";
            case log_level::info: return "info";
            case log_level::warning: return "warn";
            case log_level::error: return "error";
            case log_level::critical: return "critical";
            case log_level::off: return "off";
            default: return "unknown";
        }
    }

Referenced by format().

Here is the caller graph for this function:

---

The documentation for this class was generated from the following file:

• include/kcenon/logger/formatters/logfmt_formatter.h