Cmdliner terms for ergonomic logging configuration
Add README, LICENSE, and .gitignore
+140
+17
.gitignore
+17
.gitignore
+21
LICENSE.md
+21
LICENSE.md
···
1
+
MIT License
2
+
3
+
Copyright (c) 2025 Thomas Gazagnaire
4
+
5
+
Permission is hereby granted, free of charge, to any person obtaining a copy
6
+
of this software and associated documentation files (the "Software"), to deal
7
+
in the Software without restriction, including without limitation the rights
8
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+
copies of the Software, and to permit persons to whom the Software is
10
+
furnished to do so, subject to the following conditions:
11
+
12
+
The above copyright notice and this permission notice shall be included in all
13
+
copies or substantial portions of the Software.
14
+
15
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+
SOFTWARE.
+102
README.md
+102
README.md
···
1
+
# vlog
2
+
3
+
Cmdliner terms for ergonomic logging configuration.
4
+
5
+
## Overview
6
+
7
+
**vlog** provides cmdliner terms that configure the OCaml [Logs](https://erratique.ch/software/logs) library with a familiar CLI interface inspired by common Unix tools and Rust's `RUST_LOG` pattern.
8
+
9
+
## Features
10
+
11
+
- **Verbosity flags**: `-q`, `-v`, `-vv`, `-vvv`
12
+
- **RUST_LOG-style configuration**: `--log=level,src:level,...`
13
+
- **JSON output**: `--json` for structured logging
14
+
- **Protocol tracing**: `--trace FILE` to capture `*.tracing` sources
15
+
- **Environment variable**: `<APP>_LOG` (e.g., `MYAPP_LOG`)
16
+
17
+
## Installation
18
+
19
+
```
20
+
opam install vlog
21
+
```
22
+
23
+
## Usage
24
+
25
+
```ocaml
26
+
open Cmdliner
27
+
28
+
let run _config =
29
+
Logs.info (fun m -> m "Starting...");
30
+
(* your code *)
31
+
32
+
let cmd =
33
+
let info = Cmd.info "myapp" in
34
+
Cmd.v info Term.(const run $ Vlog.setup "myapp")
35
+
36
+
let () = exit (Cmd.eval cmd)
37
+
```
38
+
39
+
### Command Line
40
+
41
+
```bash
42
+
myapp -q # errors only
43
+
myapp # warnings (default)
44
+
myapp -v # info level
45
+
myapp -vv # debug level
46
+
myapp -vvv # debug + protocol tracing
47
+
48
+
myapp --log=debug # set level via flag
49
+
myapp --log=info,http:debug # global info, http at debug
50
+
myapp --log=warn,tls.tracing:debug # enable specific tracing
51
+
52
+
MYAPP_LOG=debug myapp # set level via env var
53
+
54
+
myapp --json # JSON output
55
+
myapp --trace protocol.log # write traces to file
56
+
```
57
+
58
+
### Verbosity Levels
59
+
60
+
| Flag | Level | `*.tracing` sources |
61
+
|--------|---------|---------------------|
62
+
| `-q` | Error | Silenced |
63
+
| (none) | Warning | Silenced |
64
+
| `-v` | Info | Silenced |
65
+
| `-vv` | Debug | Silenced |
66
+
| `-vvv` | Debug | Enabled |
67
+
68
+
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.
69
+
70
+
### JSON Output
71
+
72
+
With `--json`, use the optional `json_reporter` parameter to enable JSON log output:
73
+
74
+
```ocaml
75
+
let cmd =
76
+
let info = Cmd.info "myapp" in
77
+
Cmd.v info Term.(const run $ Vlog.setup ~json_reporter:Json_logs.reporter "myapp")
78
+
```
79
+
80
+
Requires the `json-logs` package.
81
+
82
+
## API
83
+
84
+
- `Vlog.setup` - Main cmdliner term combining all flags
85
+
- `Vlog.quiet` - Term for `-q`/`--quiet`
86
+
- `Vlog.verbosity` - Term for `-v`/`--verbose`
87
+
- `Vlog.log_term` - Term for `--log` with env var
88
+
- `Vlog.json` - Term for `--json`
89
+
- `Vlog.trace_file` - Term for `--trace FILE`
90
+
- `Vlog.parse_log_spec` - Parse RUST_LOG-style spec
91
+
- `Vlog.apply_source_overrides` - Apply per-source levels
92
+
- `Vlog.configure_tracing_sources` - Enable/disable `*.tracing` sources
93
+
94
+
## Related Work
95
+
96
+
- [logs.cli](https://erratique.ch/software/logs) - 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.
97
+
- [env_logger](https://docs.rs/env_logger/) (Rust) - The inspiration for the `--log` flag syntax and `<APP>_LOG` environment variable pattern.
98
+
- [debug](https://www.npmjs.com/package/debug) (Node.js) - Popular namespace-based debug logging. Similar concept of per-source control.
99
+
100
+
## License
101
+
102
+
MIT License. See [LICENSE.md](LICENSE.md) for details.