jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-11-03 16:01:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(relay): document sync access lines and broaden aborted

Browse Source 
List the sync event and buzz_ws_reads_total type label, say when a sync line is written and what its summary holds, and describe the causes of an aborted read beyond client disconnect.

Co-authored-by: Will Pfleger <pfleger.will@gmail.com>
Signed-off-by: Will Pfleger <pfleger.will@gmail.com>
This commit is contained in:
Will Pfleger
2026-11-02 13:54:41 -05:00
parent 19f578b135
commit 18e07aef0e
2 changed files with 14 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
.env.example
View File

@@ -237,7 +237,7 @@ RUST_LOG=buzz_relay=debug,buzz_datastore=info,buzz_db=debug,buzz_auth=debug,buzz
#
# Access log: the relay writes JSON lines for security-relevant actions under
# the `buzz_relay::access` target, with an `event` field of `http`, `auth`,
# `req`, `count`, or `close`. `http` is one line per HTTP request, written
# `req`, `count`, `sync`, or `close`. `http` is one line per HTTP request, written
# by one layer when the response is ready (not proof the body was delivered):
# `route` is the matched route template (never the raw path), with the response
# `status` and `time_to_response_ms` on every line. It carries the login
@@ -260,8 +260,13 @@ RUST_LOG=buzz_relay=debug,buzz_datastore=info,buzz_db=debug,buzz_auth=debug,buzz
# upgrades log no `http` line.
# `auth` is one line per WebSocket login, written when it succeeds or is
# refused; every root WebSocket `auth` line carries the TCP `peer_addr`.
# `req` / `count` is one line per WebSocket read, with the same filter summary
# (search text is never logged, only `search: true`). The summary lists up to
# `req` / `count` / `sync` is one line per WebSocket read (a NIP-AR sync
# subscription is a `sync` read), with the same filter summary
# (search text is never logged, only `search: true`). A `sync` line is written
# when its initial set completes, not when live delivery ends: its summary is
# the registered live filter (kinds and channels, never artifact predicates)
# and `events_queued` counts the initial set. `buzz_ws_reads_total` counts
# parsed reads by `type` (`req`, `count`, `sync`). The summary lists up to
# 10 kinds, channel ids, authors and `p` values each; `kind_count`,
# `channel_count`, `author_count` and `p_count` appear only when the list is
# `*` or shows fewer values than the filters held. `close` is the
@@ -276,8 +281,9 @@ RUST_LOG=buzz_relay=debug,buzz_datastore=info,buzz_db=debug,buzz_auth=debug,buzz
# requests are WARN. A successful `/query` or `/count` that returned nothing
# (`result_count=0`) is DEBUG, since polling clients make most of them. A
# WebSocket read is WARN only when it ends in `error`;
# refused and `aborted` reads stay INFO, since `aborted` means the client
# closed the connection mid-read, which is routine. Turn it down with
# refused and `aborted` reads stay INFO, since `aborted` means the read ended
# before completing: the client closed the connection or sent CLOSE, a same-ID
# REQ replaced it, or the session was cancelled, all of which are routine. Turn it down with
# `buzz_relay::access=warn` (keeps refusals, errors and aborted HTTP requests,
# and of WebSocket reads only `error` outcomes) or `buzz_relay::access=off` in
# RUST_LOG.

5
crates/buzz-relay/src/access.rs
View File

@@ -238,8 +238,9 @@ enum ReadOutcome {
Error(&'static str),
}
/// One access line per WebSocket REQ or COUNT, written when the handler
/// finishes, including when its future is dropped mid-read.
/// One access line per WebSocket REQ, COUNT or sync, written when the handler
/// finishes (a sync's initial set completes), including when its future is
/// dropped mid-read.
pub(crate) struct ReadLog {
event: &'static str,
conn_id: Uuid,