BitLogger/docs/api/async-logger-dropped-count.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
async-logger-dropped-count	api	async	20260512	Read the number of records dropped by the async logger because of overflow or queue clearing.	async logger queue public

Async-logger-dropped-count

Read the cumulative number of records dropped by an async logger. This metric is useful when overflow policy or forced shutdown behavior may discard queued data.

Interface

pub fn[S] AsyncLogger::dropped_count(self : AsyncLogger[S]) -> Int {}

input

• self : AsyncLogger[S] - Async logger whose dropped-record counter should be inspected.

output

• Int - Number of records dropped so far.

Explanation

Detailed rules explaining key parameters and behaviors

• The counter increases when overflow policy discards records.
• The counter can also increase when close(clear=true) or shutdown(clear=true) abandons queued records.
• It can also increase when shutdown fallback logic converts remaining pending records into dropped records during a clear-close path.
• After a worker failure short-circuits wait_idle(), that shutdown-fallback increase is runtime-dependent in the current implementation: native-worker shutdown can convert leftover pending records into additional dropped records, while compatibility shutdown can leave that closed-queue remainder visible in pending_count() instead.
• Later log attempts against an already closed queue do not add to this counter by themselves.
• This is a cumulative counter for the lifetime of the logger value.
• Use this helper when you need a focused loss metric rather than a full state() snapshot.

How to Use

Here are some specific examples provided.

When Need To Detect Loss Under Pressure

When queue overflow may discard records:

if logger.dropped_count() > 0 {
  println("async log loss detected")
}

In this example, the code checks whether the async logger has already discarded records.

When Validate Shutdown Behavior In Tests

When a test intentionally clears the queue:

logger.close(clear=true)
ignore(logger.dropped_count())

In this example, the drop counter helps confirm that abandoned backlog was tracked.

Error Case

e.g.:

• If no records have been dropped, the method simply returns 0.

• If callers need to know why records were lost, they must interpret this metric together with overflow policy and shutdown behavior.

• If wait_idle() returned early because the worker failed, dropped_count() may still stay unchanged on compatibility shutdown paths even though one leftover closed-queue item remains visible in pending_count().

Notes

1. This helper reports record loss only; it does not explain the full logger state.

2. Pair it with pending_count() or state() when investigating backlog pressure.