vlog#

Cmdliner terms for ergonomic logging configuration.

Overview#

vlog provides cmdliner terms that configure the OCaml Logs library with a familiar CLI interface inspired by common Unix tools and Rust's RUST_LOG pattern.

Features#

• Verbosity flags: -q, -v, -vv, -vvv
• RUST_LOG-style configuration: --log=level,src:level,...
• JSON output: --json for structured logging
• Protocol tracing: --trace FILE to capture *.tracing sources
• Environment variable: <APP>_LOG (e.g., MYAPP_LOG)

Installation#

opam install vlog

Usage#

open Cmdliner

let run _config =
  Logs.info (fun m -> m "Starting...");
  (* your code *)

let cmd =
  let info = Cmd.info "myapp" in
  Cmd.v info Term.(const run $ Vlog.setup "myapp")

let () = exit (Cmd.eval cmd)

Command Line#

myapp -q                            # errors only
myapp                               # warnings (default)
myapp -v                            # info level
myapp -vv                           # debug level
myapp -vvv                          # debug + protocol tracing

myapp --log=debug                   # set level via flag
myapp --log=info,http:debug         # global info, http at debug
myapp --log=warn,tls.tracing:debug  # enable specific tracing

MYAPP_LOG=debug myapp               # set level via env var

myapp --json                        # JSON output
myapp --trace protocol.log          # write traces to file

Verbosity Levels#

The -vv flag gives you application-level debug output without the noisy protocol hexdumps. Use -vvv or --trace FILE when you need full protocol tracing.

JSON Output#

With --json, use the optional json_reporter parameter to enable JSON log output:

let cmd =
  let info = Cmd.info "myapp" in
  Cmd.v info Term.(const run $ Vlog.setup ~json_reporter:Json_logs.reporter "myapp")

Requires the json-logs package.

API#

• Vlog.setup - Main cmdliner term combining all flags
• Vlog.quiet - Term for -q/--quiet
• Vlog.verbosity - Term for -v/--verbose
• Vlog.log_term - Term for --log with env var
• Vlog.json - Term for --json
• Vlog.trace_file - Term for --trace FILE
• Vlog.parse_log_spec - Parse RUST_LOG-style spec
• Vlog.apply_source_overrides - Apply per-source levels
• Vlog.configure_tracing_sources - Enable/disable *.tracing sources

Related Work#

• logs.cli - Basic cmdliner integration in the Logs library. Provides --verbosity and -v flags. vlog extends this with RUST_LOG-style per-source control, JSON output, and protocol tracing.
• env_logger (Rust) - The inspiration for the --log flag syntax and <APP>_LOG environment variable pattern.
• debug (Node.js) - Popular namespace-based debug logging. Similar concept of per-source control.

Licence#

MIT License. See LICENSE.md for details.