Expand description
The clap-logflag library can be used to add a --log
flag to
clap based command line applications that allows users to configure
logging from the command line. It can log to stderr, files and syslog, powered by the
fern logging backend.
§Examples
# Log to a single destination
$ ./your-cli --log syslog
$ ./your-cli --log file:/path/to/file
# Log to both stderr and a file
$ ./your-cli --log stderr --log file:/path/to/file
# Filter log levels. Debug (and higher) gets logged to stderr.
# Info (and higher) additionally gets logged to a file.
$ ./your-cli --log DEBUG:stderr --log INFO:file:/path/to/file
# Disable logging
$ ./your-cli --log none
# Use default logging setup (defined by the application developer)
$ ./your-cli
§Setup
To use clap-logflag, first add clap-logflag, clap and log to your Cargo.toml
.
Then, add the LogArgs struct to your clap definition and initialize logging with it:
use clap::Parser;
use clap_logflag::LoggingConfig;
use log::LevelFilter;
#[derive(Debug, Parser)]
struct CliArgs {
// Use this to add the log flags to your application
#[clap(flatten)]
log: clap_logflag::LogArgs,
// ... your other cli args ...
}
fn main() {
let args = CliArgs::parse();
// Initialize logging with the flags from clap
clap_logflag::init_logging!(
args.log
// If no `--log` arguments are present, disable logging.
// You can change this to define the default behavior,
// see the "default_logging" example.
.or_default(LoggingConfig::disabled()),
// Any `--log` argument that doesn't define a level filter will use the
// default level filter defined here, `Info` in this example.
LevelFilter::Info,
);
// Issue some log messages
log::trace!("Some trace log");
log::debug!("Some debug log");
log::info!("Some info log");
log::warn!("Some warn log");
log::error!("Some error log");
}
§Command Line Syntax
See LogArgs for a detailed explanation of the syntax for the --log
argument.
§Log Format
The format of the log messages uses an opinionated, reasonably pretty format by default. At the moment, this library does not offer a way to modify the format.
Log lines contain a UTC timestamp, the log level and an executable name.
When the logging destination is stderr and stderr is a terminal, then the log level is colorized. When logging to a file, syslog or to a stderr that is redirected to a file, the log level is not colorized.
§Help message
clap-logflag will automatically add a detailed help message to the --help
output of your application,
explaining the usage of the --log
flag to your users.
At the moment, this library does not offer a way to modify the help message.
Usage: simple_cli [OPTIONS]
Options:
--log <LOG>
Log definition consisting of an optional log level filter, and a log destination.
You can define this argument multiple times for multiple log destinations.
Logging can be disabled with `--log none`.
If combined with other log definitions, those will take precedence and logging will not be disabled.
The argument can be combined with a level filter to only log messages of a certain level or higher to that destination.
Format: destination | level_filter:destination
* level_filter = "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE"
* destination = "stderr" | "syslog" | "file:path" | "none"
Examples:
* `--log syslog`
* `--log stderr`
* `--log file:/path/to/file`
* `--log INFO:stderr`
* `--log DEBUG:file:/path/to/file`
* `--log TRACE:syslog`
* `--log none`
-h, --help
Print help (see a summary with '-h')
Macros§
- init_
logging - Initialize logging with the given configuration and default level.
Structs§
- LogArgs
- LogDestination
Config - Configuration for a log destination, containing the destination and the log level.
- Logging
Config - This enum represents the whole logging configuration, including all logging destinations and their respective log level filters.
Enums§
- LogDestination
- A destination that can be logged to, e.g. a file or the system log.
Functions§
- _init_
logging - Don’t use this function directly, use the init_logging! macro instead.