Low-noise, instance-safe logs

When adding or modifying logging, follow these rules:

1) Attribute logs to the right component/instance

• Avoid process-global logging hooks/state when a per-instance logger exists.
• Thread the instance-bound logger into call paths so warnings are correctly attributed.

2) Pick the right level and avoid noise

• Use Debug for informational-but-non-actionable signals that can be frequent.
• For streaming or chunked flows, gate warnings so they emit once per logical event (e.g., only on final chunk) rather than per chunk.

3) Never silently fall back

• If you fall back to a default behavior due to an error (e.g., URL parse failure), emit a warning with enough context to diagnose.

4) Use the logging API’s formatting instead of fmt.Sprintf

• Prefer logger.Warn("...: %v", err) over logger.Warn(fmt.Sprintf("...: %s", err)).

5) Don’t bloat request/context just to move logs

• Don’t stash ad-hoc log payloads in request context solely for later retrieval.
• Use existing streaming/middleware plumbing (e.g., dedicated completer slots) to move data explicitly.

Example patterns:

// 1+3) Instance-safe warning on fallback
if err != nil {
    logger.Warn("oauth: url parse failed, falling back to direct client: %v", err)
}

// 2) Correct level + log once (stream-aware)
if isStream && !isFinalChunk {
    // skip warning
} else {
    logger.Debug("cache: skipping write (namespace=%s, id=%s): no embedding available", ns, id)
}

// 4) Prefer format args
logger.Warn("logstore: skipping index maintenance: could not acquire index lock: %v", err)

// 5) Avoid reading logs back from fasthttp context; use dedicated slot/completer
// e.g., middleware publishes into a known slot, handler drains it after stream completes.

Applying this consistently reduces production log spam, preserves accurate attribution, improves diagnostics when fallbacks occur, and keeps logging implementation clean and maintainable.