libsyslog/

lib.rs

//! This crate provides an API implementing the standard Rust logging facade
//! to the system's syslog. That is, it implements the [Log][log::Log] trait
//! of the [log] crate for native syslog (the one typically implemented in C
//! and residing in libc).
//!
//! Syslog needs to be initialized prior to any [logging macros][log#macros]
//! being called. That is usally done through a single chained call of its
//! [builder][Syslog::builder], with optional
//! [methods][SyslogBuilder#implementations] to customize the logger before
//! finalizing the setup by calling [build][SyslogBuilder::build] and
//! [init][Syslog::init].
//!
//! Typical use: (A.k.a. recommended snippet to copy'n'paste to the start of
//! `main()` of your daemon.)
//! ```
//! # use log::error;
//! # fn main() -> Result<(), log::SetLoggerError> {
//! libsyslog::Syslog::builder()
//!     .module_level(std::module_path!(), log::LevelFilter::Info)
//!     .level(log::LevelFilter::Off)
//!     .build()
//!     .init()?;
//!
//! error!("Hello libsyslog. I've failed you.");
//! # Ok(())
//! # }
//! ```
//!
//! It is likely reasonable for most users to configure the
//! [module_level][SyslogBuilder::module_level] and
//! [level][SyslogBuilder::level] filters to only have the application's own
//! log messages sent to syslog (ignoring potentially chatty libraries), as in
//! the above example.
//!
//! The scope of this crate is limited as described by the very first paragraph
//! above. Its intended use is during normal operation, in software with modest
//! requirements on low frequency logging. Note that syslog risks killing
//! performance. Consider using another additional facade, in combination with
//! a `--no-daemon` option, for when developing and debugging. And please
//! remember, if [libsyslog][`crate`] does not meet your requirements, there
//! are plenty of other crates for logging around.

// According to [doc][], syslog() and friends are not thread safe on AIX. It
// appears there is a family or related functions with an _r suffix which
// should likely be used instead. Patches for adding AIX support are welcome.
//
// It should of course possible to locally disable the check below, but then
// it's up to you to ensure your application is single threaded.
//
#[cfg(target_os = "aix")]
compile_error!("AIX user, please help with the code comment above this error.");
//
// [doc]: https://www.ibm.com/docs/en/aix/latest?topic=s-syslog-openlog-closelog-setlogmask-subroutine

mod builder;
mod facility;
#[cfg(feature = "bitflags")]
mod logopt;
mod syslog;

#[cfg(test)]
mod tests;

#[cfg(feature = "bitflags")]
pub use logopt::*;

pub use {
    builder::*,
    facility::*,
    syslog::*,
};