From c8a80ec74b487a5e5a8d8f9355370b64e96e3761 Mon Sep 17 00:00:00 2001 From: rustdesk Date: Thu, 24 Sep 2026 10:03:30 +0800 Subject: [PATCH] docs(agents): avoid unthrottled high-frequency debug logs Debug output is written to the log file, so per-packet / per-event log sites must use trace or hbb_common's throttled_log!. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index bd6e42075..6685e48d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,6 +48,20 @@ workspace member. `base::config::keys` re-exports the handful of keys * Do not add dependencies unless needed. * Keep code simple and idiomatic. +### Logging + +* `debug` and above are written to the log file. A log call that can fire + repeatedly (per packet, frame, input event, or loop iteration, or at a rate a + peer controls) must not use `debug` or higher unthrottled. +* For such a site, pick one: + + * `log::trace!` when the event is expected and the line only helps while + actively debugging; + * `hbb_common::throttled_log!(interval, level, ...)` when it signals a fault + that should still show up in a user's log. It keeps one line per interval + with a count of the rest. Use `hbb_common::log_throttle::LogThrottle` + directly only when the decision drives more than one log call. + ## Tokio Rules * Assume a Tokio runtime already exists.