4Developers 2018: Structured logging (Bartek Szurgot)

## Overview Bartek Szurgot presents a critique of current logging practices and proposes a structured logging approach that prioritizes machine readability and type safety over traditional human-readable text logs. Rather than introducing another logging library, Szurgot argues that the fundamental approach to logging must change, particularly at scale where logs can exceed hundreds of gigabytes per second.

## Core Problem Szurgot illustrates common logging failures through a personal anecdote involving hexadecimal representation in embedded systems logs. Without enforced formatting standards, the same value appears inconsistently across logs—uppercase vs lowercase hex, with or without leading zeros, with or without 0x prefixes, or even as signed integers. When logs number in the millions, inconsistent representation makes pattern matching and automated analysis nearly impossible. The speaker notes that current logging approaches (stream operators and printf-style formatting) perpetuate these problems and make automated parsing at scale impractical.

## Proposed Solution: Structured Logging The core idea is to treat logs as data structures rather than text files. Instead of converting fully-typed values to English text and then attempting to parse that text programmatically, structured logging preserves type information and creates machine-parsable output (typically JSON). This enables automated analysis, filtering, statistics generation, and rule-based alerting without regex-based fragile parsing.

Key requirements for the proposed system include: - Uniform representation across all logs - Machine readability as primary goal - Support for user-defined types - Ease of use comparable to traditional loggers - No internal hidden state - Compile-time checking of format correctness - Support for translation and localization

## Technical Architecture The implementation centers on a recursive field_info data structure using variant types. Each field has a tag (key) and a value that can be simple (boolean, integer, string) or complex (vectors of field_info, enabling tree structures). This design preserves the hierarchical nature of logged data.

For basic logging, the API is straightforward: pass strongly-typed parameters directly without format strings. The compiler knows parameter types, enabling consistent representation through argument-dependent lookup. For optional human-readable output and translation support, a formatted variant uses compile-time format validation. The format string specifies parameter order (using dollar-index notation like $0, $1), allowing translation without changing parameter order.

The format validation happens at compile-time through constexpr functions that parse format strings and verify parameter counts match. If validation fails—mismatched counts, missing parameter indices—the compiler rejects the code immediately rather than allowing runtime errors in error-handling code paths (a critical weakness of traditional logging).

Szurgot demonstrates the field tagging pattern: simple helper functions convert user structures to field_info while applying semantic tags (e.g., tagging a string as "name" rather than generic string). This composition pattern allows complex nested structures to be logged naturally without boilerplate.

## Real-World Impact When implemented, structured logging enables new capabilities: - Automated anomaly detection (e.g., detecting performance degradation by analyzing processing-time fields) - Automatic scaling decisions in cloud environments - Support for automatic remediation (alerting support teams) - Ability to change log format retroactively through translation tables - Space optimization in embedded systems through string-to-number mapping

## Design Tradeoffs While structured logging processes more data per log entry (thus not the absolute fastest), it remains practical (hundreds to thousands of logs per second on desktop hardware) while providing actionable information. The alternative—high-volume but unstructured logs—becomes useless at scale since neither humans nor machines can process it effectively.

The proposed API design allows wrapper functions to provide domain-specific defaults, addressing different logging needs across organizations without forcing unnecessary fields. This flexibility supports various architectural requirements (distributed systems, single-machine services, etc.).

## Implementation and Availability Szurgot maintains an open-source C++14 implementation in the basic utilities and tools library (bat namespace, BSD license), which includes additional features beyond the talk (log rotation, Elasticsearch integration, Kibana support) and Docker SDK availability.