Async-logger-with-timestamp

Enable or disable automatic timestamp capture on async log emission. This API controls whether AsyncLogger::log(...) records the current time before enqueue or leaves the timestamp at 0UL.

Interface

pub fn[S] AsyncLogger::with_timestamp(self : AsyncLogger[S], enabled~ : Bool = true) -> AsyncLogger[S] {}

input

• self : AsyncLogger[S] - Base async logger whose timestamp behavior should change.
• enabled : Bool - Whether emitted records should capture current time automatically.

output

• AsyncLogger[S] - A new async logger value with updated timestamp behavior.

Explanation

Detailed rules explaining key parameters and behaviors

• When enabled, log(...) captures @env.now() before placing the record into the queue.
• When disabled, emitted records use 0UL as the timestamp value.
• This setting affects later emitted records only.
• The returned logger is derived from self; the original async logger value is not mutated.
• Only the stored timestamp flag changes. Target, minimum level, queue configuration, and lifecycle/failure state stay on the same AsyncLogger[S] surface.
• In the current direct async coverage, a derived timestamp-enabled logger records non-zero timestamps while the original logger continues emitting 0UL timestamps when it was left disabled.

How to Use

Here are some specific examples provided.

When Need Real Event Time Before Queueing

When downstream formatting or JSON output should include event time:

let logger = async_logger(console_sink())
  .with_timestamp()

In this example, each record captures its timestamp before entering the async queue.

And the returned async logger still keeps the same queue-facing API surface as the source logger.

When Need Deterministic Async Records

When timestamps should be disabled for tests or reduced output:

let logger = async_logger(console_sink())
  .with_timestamp(enabled=false)

In this example, queued records are emitted without runtime time capture.

Error Case

e.g.:

• If timestamps are disabled, formatters that expect meaningful time values may show empty or zero-like timestamp output.

• If callers need timestamps only for one record, a separate logger value is usually clearer than toggling behavior repeatedly.

Notes

1. This API controls record creation before enqueue, not formatter display policy.

2. It is useful for tests, deterministic snapshots, and production timing.

3. State helpers such as pending_count(), dropped_count(), is_closed(), and has_failed() remain available on the returned logger because the visible async logger surface is preserved.

4. Use a derived logger value when only one branch should capture timestamps and the base logger should remain deterministic.