What Happens to Log Messages That Exceed Circular Buffer Capacity in tui-logger Versions Before 0.13

In tui-logger versions prior to 0.13, log messages that exceed the circular buffer capacity are silently overwritten and lost without any diagnostic warning or notification.

The gin66/tui-logger crate uses a hot circular buffer to stage log events before they are rendered in a TUI widget. When applications generate logs faster than the UI draws them, this buffer can fill up completely. Understanding how the library handles this overflow is critical for debugging missing log entries in older deployments.

Silent Message Loss in Pre-0.13 Releases

Before version 0.13, the hot buffer implementation provided no safety mechanism for overflow scenarios. When the number of emitted log records (total) exceeded the buffer's fixed capacity (elements), the circular buffer simply wrapped around and overwrote the oldest entries.

This behavior meant that high-volume logging sessions could drop messages permanently without leaving any trace in the output stream. The README explicitly documents this risk: "In versions < 0.13 log messages may have been lost, if the widget wasn't drawn."【/cache/repos/github.com/gin66/tui-logger/master/README.md#L221-L222】

The following example demonstrates how 500 messages disappear silently when writing 1500 records to a buffer with capacity for 1000:

// Hot buffer depth configured to 1000 entries
// Application emits 1500 messages before UI render cycle
for i in 0..1500 {
    log::info!("message {}", i);
}

// Pre-0.13 behavior: Messages 0-499 are overwritten and irrecoverable
// No warning indicates the data loss occurred

Version 0.13+ Overrun Detection and Reporting

Starting with version 0.13, the library introduces explicit loss detection in the move_events() function within src/logger/inner.rs. When the buffer overflows, the system now calculates the number of dropped events and injects a synthetic ExtLogRecord into the log stream to report the loss【/cache/repos/github.com/gin66/tui-logger/master/src/logger/inner.rs#L49-L55】.

The ExtLogRecord::overrun() helper method formats a diagnostic message indicating exactly how many events were lost versus how many were successfully recorded【/cache/repos/github.com/gin66/tui-logger/master/src/logger/inner.rs#L96-L111】.

Under the same scenario, modern versions produce visible output:

// Same 1500 messages written to 1000-entry buffer
for i in 0..1500 {
    log::info!("message {}", i);
}

// Post-0.13 behavior: move_events() detects the overflow and adds:
// "There have been 500 events lost, 1000 recorded out of 1500"

Key Implementation Details

The Circular Buffer Architecture

The underlying storage mechanism lives in src/circular.rs, which provides the ring buffer implementation used for both hot and main log storage. This module manages the wrap-around logic that overwrites old entries when the buffer reaches capacity, but it does not itself track whether overwrite events occurred.

Loss Detection Logic in move_events()

The critical detection happens at lines 49-55 of src/logger/inner.rs. The move_events() function compares the total number of events received against the number of elements actually stored in the buffer. When total > elements, the code calculates the difference as the lost message count and triggers the overrun reporting path.

Formatting Overrun Warnings

The ExtLogRecord::overrun() implementation (lines 96-111 in the same file) constructs the warning text that appears in the log output. This method generates a descriptive string quantifying the data loss, making buffer overflows visible to developers rather than hiding them silently.

Summary

• Pre-0.13 behavior: Excess log messages overwrite old entries silently, causing permanent data loss without warning【/cache/repos/github.com/gin66/tui-logger/master/README.md#L221-L222】.
• Post-0.13 improvement: The move_events() function detects overflow and inserts synthetic records via ExtLogRecord::overrun() to report exactly how many messages were dropped【/cache/repos/github.com/gin66/tui-logger/master/src/logger/inner.rs#L49-L55】.
• Buffer implementation: The circular buffer logic in src/circular.rs handles the physical storage but relies on the logger inner module to track overflow events.
• Impact: Applications using tui-logger versions before 0.13 risk missing critical log data during high-frequency logging bursts if the UI thread fails to draw promptly.

Frequently Asked Questions

How can I detect if messages were lost in tui-logger versions before 0.13?

You cannot detect loss programmatically within the library itself in versions prior to 0.13. Since the buffer overwrites old entries without recording the event, there is no API to query for dropped messages. You must either upgrade to v0.13+ or implement external counters to compare messages emitted versus messages displayed.

What is the default capacity of the hot circular buffer?

The default capacity depends on your initialization configuration, but the buffer size is fixed at creation time. When instantiation occurs, you specify the depth for the hot buffer that stages events before TUI rendering. Once this limit is reached in pre-0.13 code, every new message forces out the oldest one.

Does tui-logger v0.13+ still drop messages or does it prevent overflow?

Version 0.13 and later still drops messages when the buffer fills up, but it no longer does so silently. The library adds a diagnostic entry to the log stream indicating exactly how many events were lost. It does not block the logging thread or expand the buffer dynamically; it merely makes the overflow condition visible to operators.

Which source files control the buffer overflow behavior?

The overflow logic spans two primary files: src/circular.rs contains the raw ring buffer that handles the physical overwrite mechanism, while src/logger/inner.rs implements the loss detection and warning generation through move_events() and ExtLogRecord::overrun()【/cache/repos/github.com/gin66/tui-logger/master/src/logger/inner.rs#L49-L111】.

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