[−][src]Crate spirit_log
A spirit fragments and helpers to configure and control logging.
The Fragment
s here allow to configure relatively complex logging (multiple loggers,
different formats, different destinations), both from command line and the configuration. It
allows runtime reloading of them.
Internally it is based on the fern
crate and just adds the configuration and runtime
reloading (through [log-reroute
]).
It assumes the application doesn't set the global logger itself. It also sets the panic hook
through the [log_panics
] crate. The with-backtrace
cargo feature is propagated through.
Startup
The logging is set in multiple steps:
- As soon as the pipeline is registered, a logging on the
WARN
level is sent tostderr
. - After command line arguments are parsed the
stderr
logging is updated to reflect that (or left on theWARN
level if nothing is set by the user). - After configuration is loaded from the files, full logging is configured.
Integration with other loggers
If you need something specific (for example sentry
), you
can plug in additional loggers through the pipeline ‒ the Dispatch
allows adding arbitrary
loggers. The Pipeline::map
is a good place to do
it.
Performance warning
This allows the user to create arbitrary number of loggers. Furthermore, the logging is synchronous by default and not buffered. When writing a lot of logs or sending them over the network, this could become a bottleneck.
Background logging
The background
feature flag adds the ability to do the actual logging in a background thread.
This allows not blocking the actual application by IO or other expensive operations.
On the other hand, if the application crashes, some logs may be lost (or, depending on setup,
when the logging thread doesn't keep up). Also, you need to flush the logger on shutdown, by
using the FlushGuard
.
It is done through the Background
transformation.
Planned features
These pieces are planned some time in future, but haven't happened yet.
- Reconnecting to the remote server if a TCP connection is lost.
- Log file rotation.
- Colors on
stdout
/stderr
.
Usage without Pipelines
It is possible to use without the Pipeline
, manually. However,
certain care needs to be taken to initialize everything that needs to be initialized.
It is either possible to just get the Dispatch
object and call apply
,
that however is a single-shot initialization and the logger can't be replaced.
The helper functions init
and install
can be used to gain the ability to replace
Dispatch
loggers multiple times.
Examples
Manual single use installation
use spirit::prelude::*; use spirit_log::Cfg; // Well, you'd get it somewhere from configuration, but… let cfg = Cfg::default(); let logger = cfg.create("logger")?; logger.apply()?;
Manual multiple-use installation
use spirit::prelude::*; use spirit_log::Cfg; spirit_log::init(); // This part can be done multiple times. let cfg = Cfg::default(); let logger = cfg.create("logger")?; spirit_log::install(logger);
Automatic usage with a Pipeline, reloading and command line options
use log::info; use serde::Deserialize; use spirit::prelude::*; use spirit_log::{Cfg as LogCfg, CfgAndOpts as LogBoth, Opts as LogOpts}; use structopt::StructOpt; #[derive(Clone, Debug, StructOpt)] struct Opts { #[structopt(flatten)] log: LogOpts, } impl Opts { fn log(&self) -> LogOpts { self.log.clone() } } #[derive(Clone, Debug, Default, Deserialize)] struct Cfg { #[serde(flatten)] log: LogCfg, } impl Cfg { fn log(&self) -> LogCfg { self.log.clone() } } fn main() { Spirit::<Opts, Cfg>::new() .with( Pipeline::new("logging").extract(|opts: &Opts, cfg: &Cfg| LogBoth { cfg: cfg.log(), opts: opts.log(), }), ) .run(|_spirit| { info!("Hello world"); Ok(()) }); }
The configuration could look something like this:
[[logging]]
level = "DEBUG"
type = "file"
filename = "/tmp/example.log"
clock = "UTC"
Re-exports
pub use background::Background; |
pub use background::FlushGuard; |
pub use background::OverflowMode; |
Modules
background | Support for logging in the background. |
Structs
Cfg | A configuration fragment to set up logging. |
CfgAndOpts | |
LogInstaller | |
Opts | A fragment for command line options. |
SyslogError | This error can be returned when initialization of logging to syslog fails. |
Functions
init | Initialize the global state. |
install | Replace the current logger with the provided one. |
install_parts | Replace the current logger with the provided one. |