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#

Install with opam:

$ opam install vlog

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install vlog

Usage#

open Cmdliner

let run () =
  Logs.info (fun m -> m "Starting...");
  Ok ()

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

let main () = exit (Cmd.eval_result 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:

open Cmdliner

let run () = `Ok ()

let json_reporter ~app:_ ~base:_ () = Logs.nop_reporter

let cmd =
  let info = Cmd.info "myapp" in
  Cmd.v info
    Term.(const run $ Vlog.setup ~json_reporter:(Some json_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.