logging: operator guide + --logging/--log-handler multi-flag support

[gmarzot]

Summary

Adds docs/logging.md — a comprehensive operator-facing guide for the folly XLOG framework that now governs every layer of moqx's stack (moxygen, fizz, wangle, mvfst, picoquic transport bridge, with proxygen and folly itself to follow).

What's in it

• TL;DR table — 8 most common operational scenarios with the exact flag to run
• Three-layer config model — compile-time baseline → env vars → CLI flag, with override semantics
• Category hierarchy — moqx.*, moxygen.*, quic.{mvfst,picoquic}.* and the multi-QUIC-stack disambiguation pattern
• Severity ladder — DBG9..DBG0, INFO, WARN, ERR, CRITICAL, FATAL with conventions for what each layer emits per level
• Async behavior + sync_level escalation — default async=true, sync_level=WARN; important events still flush synchronously
• ~10 worked examples — production deployment, hot-path tracing, per-class filtering, qlog coexistence, etc.
• Migration table — legacy glog flag → XLOG equivalent
• Troubleshooting — the common "why is nothing being logged" / "log file doesn't exist" / "category isn't matching" scenarios

Why now

The stack-wide migration to folly XLOG is now real on main:

• fizz/wangle/mvfst selector PRs landed (feat: Add TrackFilterLoadTest (live-relay blackbox load test) #168/refactor: remove MoQForwarder unit tests from MoqxRelayTest #252/#456 upstream) and standalone: folly XLOG backend for bundled deps + override knobs moxygen#246 wires them up
• transport/pico: PicoQuicXLogSink — route picoquic internal logs through folly XLOG moxygen#256 just merged: picoquic's internal C-side log events now flow through XLOG as well

This doc gives operators a single place to learn the new logging model. It's intentionally a living reference — additional findings during end-to-end vetting of the bridge will accumulate here as follow-up PRs against this same file.

Test plan

• Verify each TL;DR row reproduces against a local moqx run once the moxygen sync for Quic Metrics fix quicActiveStreams going negative #256 lands
• Verify the category hierarchy section reflects observed XLOG category names from a live run
• Verify the severity-mapping section against actual picoquic/fizz/wangle/mvfst log emission at each level
• Verify the troubleshooting section against real failure modes (one operator dry-run from scratch)

---

This change is 

[mondain]

@mondain reviewed 7 files and all commit messages, and made 1 comment.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on afrind, akash-a-n, peterchave, suhasHere, and TimEvens).

[afrind]

I find the guide to be too long, with redundant information and excessive detail cluttering things. Maybe have the agent make another pass to crisp it up?

@afrind reviewed 7 files and all commit messages, and made 8 comments.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on akash-a-n, peterchave, suhasHere, and TimEvens).

---

docs/logging.md line 3 at r1 (raw file):

# Logging

moqx and every layer of its stack (moxygen, fizz, wangle, mvfst, picoquic transport, and over time proxygen and folly itself) emit logs through **folly's XLOG framework**. A single CLI flag controls the entire stack uniformly:

Suggestion:

moqx and every layer of its stack (moxygen, fizz, wangle, mvfst, picoquic transport, and over time proxygen and folly itself) emit debug logs through **folly's XLOG framework**. A single CLI flag controls the entire stack uniformly:

---

docs/logging.md line 23 at r1 (raw file):

| Crank everything (firehose) | `moqx … --logging=DBG4` |
| Production: log to file, WARN baseline | `moqx … --logging=WARN --log-handler=default:async=true,sync_level=WARN` |
| Hot-path tracing without losing throughput | `moqx … --logging=moqx=DBG4 --log-handler=default:async=true,sync_level=WARN` (async on by default already) |

I was wondering how this was different from "Crank everything". Is the answer: because any --logging string automatically nukes async:true? That is probably unexpected, so maybe we should add async:true unless the log string has async:false?

---

docs/logging.md line 164 at r1 (raw file):

  moxygen.MoQFramer               Wire format encode/decode
  moxygen.MoQCodec                Per-stream framing
  moxygen.MoQForwarder            Track-level multiplex to subscribers

Is it not moxygen.relay.MoQForwarder?

---

docs/logging.md line 165 at r1 (raw file):

  moxygen.MoQCodec                Per-stream framing
  moxygen.MoQForwarder            Track-level multiplex to subscribers
  moxygen.MoQCache                Forward-cache (object/group lookup)

We don't use MoQCache

---

docs/logging.md line 342 at r1 (raw file):

- **XLOG** is the operator/dev surface — uniform across the stack, async, controlled by `--logging=`.
- **qlog** is the IETF-standard structured QUIC log — JSON files for tooling like [qvis](https://qvis.quictools.info/) to analyze packet timelines, congestion control, and stream events.

This can also be an operator/dev surface. The distinction is the

a) standard, structured format can be consumed by external tools
b) moqx (will soon) support enabling mlog/qlog on a per-session basis, including random sampling

--logging is good for "what just went wrong" and clues embedded in the code

mlog is good for "I want a trace of a single session"

---

src/LoggingMultiFlag.cpp line 16 at r1 (raw file):

namespace {

void joinNonEmpty(std::string& out, char sep, const std::vector<folly::StringPiece>& values) {

I think std::string_view is preferred to StringPiece unless needed for compat now?

---

src/main.cpp line 79 at r1 (raw file):

  // any multiple instances into a single composite before folly::Init
  // sees them — lets operators write `--logging=A --logging=B` instead
  // of having to shell-quote `--logging='A;B'`.

consider condensing comment to 1 or maybe 2 lines

[afrind]

Also the PR title is somewhat misleading because there's C++ code here to do the log arg consolidation

[afrind]

@afrind reviewed 5 files and all commit messages, and made 2 comments.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on akash-a-n, peterchave, suhasHere, and TimEvens).

---

docs/logging.md line 121 at r2 (raw file):

| `DBG6`–`DBG9` | Byte-level, executor tasks, queue stats | Forensic |

If you see `ERR` in steady state, file a bug. Steady `WARN` hints at an edge case the system is handling.

Oof - ok

---

docs/logging.md line 170 at r2 (raw file):

Independent channels — enabling one doesn't suppress the other.

## Migration from the old (glog) flags

Do we need this section? It's not like we have a giant user base.