v0.2.0

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
  push:
- branches: [ main, master, 'feature/**' ]
+ branches: [ '**' ]
  tags: ['v*']
  pull_request:
  workflow_dispatch:

.github/workflows/lint.yml

@@ -4,8 +4,7 @@ on:
  pull_request:
  push:
  branches:
- - main
- - feature/**
+ - '**'
 
 permissions:
  contents: read

README.md

@@ -10,7 +10,7 @@ Trace helps you collect structured runtime logs in Arduino ESP32 projects with b
 
 ## Why use Trace?
 
-* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths have separate configured limits.
+* **Bounded memory** - recent history, realtime delivery, pending flush logs, and payload lengths use fixed-capacity storage.
 * **Structured output** - log records keep level, tag, message, formatted text, sequence, and uptime.
 * **Task-side callbacks** - realtime observation and persistence callbacks run from the internal Trace task.
 * **ESP32 task control** - configure byte stack size, priority, core affinity, and stack memory preference.
@@ -80,15 +80,18 @@ void loop() {
 * `maxRecentLogs` controls queryable in-RAM history only.
 * `maxRealtimeLogs` controls the realtime delivery queue used by `onLog()` and stream output.
 * `maxPendingLogs` controls unsaved logs waiting for flush.
-* Queue-count `0` disables that queue. Payload-cap `0` means unlimited.
+* Queue-count `0` disables that queue. Payload-cap `0` uses the compiled maximum for that payload type.
 * `setStream()` writes formatted realtime logs to any Arduino `Print` stream such as `Serial`, `Serial1`, `WiFiClient`, or a custom sink.
 * Stream output uses ANSI colors by default. Callback, flush, and query `TraceLog::formatted` values stay plain text.
+* After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+* Query APIs, flush batch conversion, `onLog()` conversion, stream implementations, and user-created `std::string` values may still allocate.
 * `onLog()` is for realtime observation; `onFlush()` is for persistence.
 * Callbacks should avoid long blocking work and should not recursively call Trace logging methods.
 * Trace does not own attached `Print` or `Tempo` instances. Keep them alive until `Trace::end()` completes.
 * Detaching or replacing `Print` or `Tempo` while Trace is active does not synchronize already snapshotted worker use.
 * Stack sizes are FreeRTOS byte sizes on ESP32 and must be at least 1024 bytes.
 * `TraceStackType::Auto` prefers PSRAM task stacks when supported and falls back to internal RAM.
+* `TraceStorageMemory::PreferPsram` opts recent and pending log buffers into PSRAM with internal fallback. Realtime delivery stays internal.
 
 ## Examples
 
@@ -149,16 +152,17 @@ For the full API, see [`docs/api.md`](docs/api.md).
 | Platform | `espressif32` |
 | Language | C++20 |
 | Filesystem | none |
-| PSRAM | Optional for task stacks when ESP-IDF support is available |
+| PSRAM | Optional for task stacks and opt-in recent/pending log storage |
 | Dependencies | `bblanchon/ArduinoJson >= 7.0.0` |
 | Exceptions | Not used |
-| Status | Early-stage `0.1.0` |
+| Status | Release `0.2.0` |
 
 ## Configuration
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;

docs/api.md

@@ -12,7 +12,7 @@
 
 `TraceFlushResult` values are `Ok`, `Failed`, and `Retry`.
 
-`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout.
+`Ok` removes flushed pending logs. `Failed` is terminal for the current `flushAndWait()` call but retains pending logs. `Retry` retains pending logs, schedules another attempt using `TraceConfig::retryIntervalMs`, and keeps `flushAndWait()` waiting until `Ok`, `Failed`, or timeout. Normal flush requests do not bypass the retry deadline; urgent error and fatal flush requests may bypass it.
 
 ## Main methods
 
@@ -67,6 +67,8 @@ std::vector<TraceLog> getLastLogs(size_t count);
 std::vector<TraceLog> getLogsByTag(const char *tag);
 ```
 
+`TraceDiag` includes queue counts, drop and flush counters, task stack information, queue allocation byte counts, and PSRAM placement flags for recent, realtime, and pending queues.
+
 ## TraceLog
 
 `TraceLog` stores `sequence`, `level`, `tag`, `message`, `formatted`, `timeText`, `uptimeMs`, and `truncated`.

docs/configuration.md

@@ -1,13 +1,14 @@
 # Configuration
 
-`TraceConfig` controls the internal task, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
+`TraceConfig` controls the internal task, log storage memory, log limits, flush timing, overflow behavior, JSON formatting, level filtering, and stream colors.
 
 ```cpp
 TraceConfig config;
 config.stackSize = 4096;
 config.priority = 1;
 config.coreId = tskNO_AFFINITY;
 config.stackType = TraceStackType::Auto;
+config.storageMemory = TraceStorageMemory::Internal;
 config.maxRecentLogs = 100;
 config.maxRealtimeLogs = 100;
 config.maxPendingLogs = 50;
@@ -35,7 +36,21 @@ config.maxFormattedLength = 384;
 
 `maxPendingLogs = 0` disables persistence buffering. Logs are still accepted for recent history and realtime delivery, but they are counted as dropped for persistence.
 
-Queue-count `0` means disabled. Payload-cap `0` means unlimited.
+Queue-count `0` means disabled. Payload-cap `0` means use the compiled maximum for that payload type.
+
+## Storage memory
+
+Trace stores recent, realtime, and pending logs in fixed-capacity ring buffers. Each enabled queue is allocated once during `init()`.
+
+After `Trace::init()`, accepted direct C-string log calls do not allocate on the internal enqueue path when all target queues have capacity and no output-boundary conversion is triggered.
+
+This guarantee is intentionally narrow. Query APIs allocate `std::vector<TraceLog>`, flush batch conversion and `onLog()` conversion can allocate because public `TraceLog` contains `std::string`, stream implementations may allocate internally, and user code may allocate before passing `std::string` values to Trace.
+
+`TraceStorageMemory::Internal` is the deterministic default. Recent, realtime, and pending queues use internal-capable memory.
+
+`TraceStorageMemory::PreferPsram` uses PSRAM for recent and pending queues when PSRAM is available, otherwise it falls back to internal-capable memory. The realtime queue remains internal.
+
+`TraceStorageMemory::RequirePsram` requires recent and pending queues to allocate in PSRAM. `init()` returns `TraceStatus::OutOfMemory` if PSRAM is unavailable or allocation fails. The realtime queue remains internal.
 
 ## Payload limits
 
@@ -45,6 +60,17 @@ Queue-count `0` means disabled. Payload-cap `0` means unlimited.
 
 `maxFormattedLength` applies to `printf`-style and JSON-formatted input before it becomes `TraceLog::message`.
 
+Runtime payload limits are bounded by compile-time caps:
+
+```cpp
+TRACE_RECORD_MAX_TAG_LENGTH
+TRACE_RECORD_MAX_MESSAGE_LENGTH
+TRACE_FORMATTED_BUFFER_LENGTH
+TRACE_TIME_TEXT_BUFFER_LENGTH
+```
+
+Setting a runtime limit above the compiled cap clamps to the compiled cap. Setting a runtime payload limit to `0` uses the compiled cap.
+
 When Trace truncates a log, `TraceLog::truncated` is set. `TraceDiag::truncatedLogCount` increments once per log record, even if both tag and message were truncated.
 
 ## Flush triggers
@@ -56,7 +82,7 @@ Trace flushes pending logs when:
 * `flushIntervalMs` elapses with pending logs.
 * `flushOnError` is enabled and an `Error` or `Fatal` log is queued.
 
-`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop.
+`retryIntervalMs` controls the delay after `TraceFlushResult::Retry`. Values smaller than the worker poll interval are clamped so retry cannot spin in a tight loop. Normal flush requests set `flushRequested` but do not clear or bypass the retry deadline. Urgent error and fatal flush requests may bypass the retry deadline.
 
 ## Flush results
 
@@ -74,7 +100,7 @@ Trace flushes pending logs when:
 
 `BlockCaller` requests a flush and waits up to `blockCallerTimeoutMs` for pending space.
 
-`FlushImmediately` requests a flush immediately and retries until space appears or `blockCallerTimeoutMs` expires.
+`FlushImmediately` requests a flush immediately and queues the new record only if pending space becomes available before `blockCallerTimeoutMs` expires.
 
 ## Stack policy
 

library.json

@@ -1,6 +1,6 @@
 {
  "name": "Trace",
- "version": "0.1.0",
+ "version": "0.2.0",
  "description": "Logging and diagnostics library for ESP32 devices with bounded buffers and task-side flushing.",
  "keywords": [
  "esp32",

library.properties

@@ -1,5 +1,5 @@
 name=Trace
-version=0.1.0
+version=0.2.0
 author=zekageri
 maintainer=zekageri
 sentence=Logging and diagnostics library for ESP32 devices.

src/Trace.h

@@ -13,6 +13,22 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 
+#ifndef TRACE_RECORD_MAX_TAG_LENGTH
+#define TRACE_RECORD_MAX_TAG_LENGTH 32
+#endif
+
+#ifndef TRACE_RECORD_MAX_MESSAGE_LENGTH
+#define TRACE_RECORD_MAX_MESSAGE_LENGTH 256
+#endif
+
+#ifndef TRACE_FORMATTED_BUFFER_LENGTH
+#define TRACE_FORMATTED_BUFFER_LENGTH 384
+#endif
+
+#ifndef TRACE_TIME_TEXT_BUFFER_LENGTH
+#define TRACE_TIME_TEXT_BUFFER_LENGTH 48
+#endif
+
 class Tempo;
 struct TraceImpl;
 
@@ -43,6 +59,12 @@ enum class TraceStackType : uint8_t {
 	Psram,
 };
 
+enum class TraceStorageMemory : uint8_t {
+	Internal,
+	PreferPsram,
+	RequirePsram,
+};
+
 enum class TraceOverflowPolicy : uint8_t {
 	DropOldestPending,
 	DropNewest,
@@ -89,6 +111,7 @@ struct TraceConfig {
 	UBaseType_t priority = 1;
 	BaseType_t coreId = tskNO_AFFINITY;
 	TraceStackType stackType = TraceStackType::Auto;
+	TraceStorageMemory storageMemory = TraceStorageMemory::Internal;
 	size_t maxRecentLogs = 100;
 	size_t maxRealtimeLogs = 100;
 	size_t maxPendingLogs = 50;
@@ -146,6 +169,12 @@ struct TraceDiag {
 	size_t stackHighWaterMarkBytes = 0;
 	TraceStackType requestedStackType = TraceStackType::Auto;
 	TraceStackType actualStackType = TraceStackType::Internal;
+	size_t recentAllocatedBytes = 0;
+	size_t realtimeAllocatedBytes = 0;
+	size_t pendingAllocatedBytes = 0;
+	bool recentLogsInPsram = false;
+	bool realtimeLogsInPsram = false;
+	bool pendingLogsInPsram = false;
 };
 
 using TraceTimeFormatter = bool (*)(const Tempo &tempo, char *buffer, size_t bufferSize);
@@ -242,6 +271,14 @@ class Trace {
 
  private:
 	TraceResult log(TraceLevel level, const char *tag, const std::string &message);
+	TraceResult logRaw(
+ TraceLevel level,
+ const char *tag,
+ size_t tagLen,
+ const char *message,
+ size_t messageLen,
+ bool alreadyTruncated
+	);
 	TraceResult logJson(TraceLevel level, const char *tag, const JsonDocument &doc);
 	TraceResult logVPrintf(TraceLevel level, const char *tag, const char *format, va_list args);
 
@@ -260,14 +297,18 @@ class Trace {
  return TraceResult::failure(TraceStatus::InvalidArgument, "format failed");
  }
  const size_t limit = getMaxFormattedLength();
- const bool unlimited = limit == 0;
  const size_t outputLength = static_cast<size_t>(needed);
- const size_t boundedLength = unlimited ? outputLength : std::min(outputLength, limit);
- std::vector<char> buffer(boundedLength + 1);
- snprintf(buffer.data(), buffer.size(), format, args...);
- return log(level, tag, std::string(buffer.data()), !unlimited && outputLength > limit);
+ const size_t boundedLength = std::min(outputLength, limit);
+ char buffer[TRACE_FORMATTED_BUFFER_LENGTH + 1] = {};
+ snprintf(buffer, boundedLength + 1, format, args...);
+ const size_t tagLimit = getMaxTagLength();
+ const size_t tagLen = boundedStrLen(tag, tagLimit + 1);
+ return logRaw(level, tag, tagLen, buffer, boundedLength, outputLength > limit);
 	}
 
+	static size_t boundedStrLen(const char *value, size_t maxLen);
+	size_t getMaxTagLength() const;
+	size_t getMaxMessageLength() const;
 	size_t getMaxFormattedLength() const;
 	TraceResult log(
  TraceLevel level,

src/TraceFlush.cpp

@@ -17,8 +17,14 @@ void TraceImpl::performFlush() {
  return;
  }
  callback = onFlush;
- batch.logs = pendingLogs;
  batch.createdAtUptimeMs = millis();
+ batch.logs.reserve(pendingLogs.size());
+ for (size_t i = 0; i < pendingLogs.size(); ++i) {
+ TraceRecord record;
+ if (pendingLogs.peek(i, record)) {
+ batch.logs.push_back(toPublicLog(record));
+ }
+ }
  if (!batch.logs.empty()) {
  maxSequence = batch.logs.back().sequence;
  }
@@ -46,16 +52,10 @@ void TraceImpl::performFlush() {
  if (flushResult == TraceFlushResult::Ok) {
  nextFlushAttemptMs = 0;
  if (maxSequence > 0) {
- pendingLogs.erase(
- std::remove_if(
- pendingLogs.begin(),
- pendingLogs.end(),
- [maxSequence](const TraceLog &log) {
- return log.sequence <= maxSequence;
- }
- ),
- pendingLogs.end()
- );
+ TraceRecord record;
+ while (pendingLogs.peek(0, record) && record.sequence <= maxSequence) {
+ pendingLogs.pop(record);
+ }
  }
  flushSuccessCount++;
  } else if (flushResult == TraceFlushResult::Retry) {
@@ -76,13 +76,19 @@ bool TraceImpl::shouldFlushNow() {
 	if (!lock) {
  return false;
 	}
+	const uint64_t nowMs = millis();
+	if (
+ !pendingLogs.empty() && nextFlushAttemptMs > 0 && nowMs < nextFlushAttemptMs &&
+ !urgentFlushRequested
+	) {
+ return false;
+	}
 	if (flushRequested || urgentFlushRequested) {
  return true;
 	}
 	if (pendingLogs.empty()) {
  return false;
 	}
-	const uint64_t nowMs = millis();
 	if (nextFlushAttemptMs > 0) {
  return nowMs >= nextFlushAttemptMs;
 	}