Struct sloggers::syslog::SyslogBuilder

pub struct SyslogBuilder { /* fields omitted */ }

A logger builder which builds loggers that send log records to a syslog server.

All settings have sensible defaults. Simply calling SyslogBuilder::new().build() will yield a functional, reasonable Logger in most situations. However, most applications will want to set the facility.

The resulting logger will work asynchronously (the default channel size is 1024).

Example

use slog::info;
use sloggers::Build;
use sloggers::types::Severity;
use sloggers::syslog::{Facility, SyslogBuilder};
use std::ffi::CStr;

let logger = SyslogBuilder::new()
    .facility(Facility::User)
    .level(Severity::Debug)
    .ident(CStr::from_bytes_with_nul(b"sloggers-example-app\0").unwrap())
    .build()?;

info!(logger, "Hello, world! This is a test message from `sloggers::syslog`.");

Implementations

impl SyslogBuilder

pub fn new() -> Self

Makes a new SyslogBuilder instance.

pub fn source_location(&mut self, source_location: SourceLocation) -> &mut Self

Sets the source code location type this logger will use.

pub fn facility(&mut self, facility: Facility) -> &mut Self

Sets the syslog facility to send logs to.

By default, this is the user facility.

pub fn overflow_strategy(
    &mut self,
    overflow_strategy: OverflowStrategy
) -> &mut Self

Sets the overflow strategy for the logger.

pub fn ident_str(&mut self, ident: impl AsRef<str>) -> &mut Self

Sets the name of this program, for inclusion with log messages. (POSIX calls this the “tag”.)

The supplied string must not contain any zero (ASCII NUL) bytes.

Default value

If a name is not given, the default behavior depends on the libc implementation in use.

BSD, GNU, and Apple libc use the actual process name. µClibc uses the constant string syslog. Fuchsia libc and musl libc use no name at all.

When to use

This method converts the given string to a C-compatible string at run time. It should only be used if the process name is obtained dynamically, such as from a configuration file.

If the process name is constant, use the ident method instead.

Panics

This method panics if the supplied string contains any null bytes.

Example

use sloggers::Build;
use sloggers::syslog::SyslogBuilder;

let my_ident: String = some_string;

let logger = SyslogBuilder::new()
    .ident_str(my_ident)
    .build()
    .unwrap();

Data use and lifetime

This method takes an ordinary Rust string, copies it into a CString (which appends a null byte on the end), and passes that to the ident method.

pub fn ident(&mut self, ident: impl Into<Cow<'static, CStr>>) -> &mut Self

Sets the name of this program, for inclusion with log messages. (POSIX calls this the “tag”.)

Default value

If a name is not given, the default behavior depends on the libc implementation in use.

BSD, GNU, and Apple libc use the actual process name. µClibc uses the constant string syslog. Fuchsia libc and musl libc use no name at all.

When to use

This method should be used if you already have a C-compatible string to use for the process name, or if the process name is constant (as opposed to taken from a configuration file or command line parameter).

Data use and lifetime

This method takes a C-compatible string, either owned or with the 'static lifetime. This ensures that the string remains available for the entire time that the system libc might need it (until closelog is called, which happens when the built Logger is dropped).

Example

use sloggers::Build;
use sloggers::syslog::SyslogBuilder;
use std::ffi::CStr;

let logger = SyslogBuilder::new()
    .ident(CStr::from_bytes_with_nul("sloggers-example-app\0".as_bytes()).unwrap())
    .build()
    .unwrap();

pub fn log_pid(&mut self) -> &mut Self

Include the process ID in log messages.

pub fn log_ndelay(&mut self) -> &mut Self

Immediately open a connection to the syslog server, instead of waiting until the first log message is sent.

log_ndelay and log_odelay are mutually exclusive, and one of them is the default. Exactly which one is the default depends on the platform, but on most platforms, log_odelay is the default.

On OpenBSD 5.6 and newer, this setting has no effect, because that platform uses a dedicated system call instead of a socket for submitting syslog messages.

pub fn log_odelay(&mut self) -> &mut Self

Don’t immediately open a connection to the syslog server. Wait until the first log message is sent before connecting.

log_ndelay and log_odelay are mutually exclusive, and one of them is the default. Exactly which one is the default depends on the platform, but on most platforms, log_odelay is the default.

On OpenBSD 5.6 and newer, this setting has no effect, because that platform uses a dedicated system call instead of a socket for submitting syslog messages.

pub fn log_nowait(&mut self) -> &mut Self

If a child process is created to send a log message, don’t wait for that child process to exit.

This option is highly unlikely to have any effect on any modern system. On a modern system, spawning a child process for every single log message would be extremely slow. This option only ever existed as a workaround for limitations of the 2.11BSD kernel, and was already deprecated as of 4.4BSD. It is included here only for completeness because, unfortunately, POSIX defines it.

pub fn log_perror(&mut self) -> &mut Self

Also emit log messages on stderr (see warning).

Warning

The libc syslog function is not subject to the global mutex that Rust uses to synchronize access to stderr. As a result, if one thread writes to stderr at the same time as another thread emits a log message with this option, the log message may appear in the middle of the other thread’s output.

Note that this problem is not specific to Rust or this crate. Any program in any language that writes to stderr in one thread and logs to syslog with LOG_PERROR in another thread at the same time will have the same problem.

The exception is the syslog implementation in GNU libc, which implements this option by writing to stderr through the C stdio API (as opposed to the write system call), which has its own mutex. As long as all threads write to stderr using the C stdio API, log messages on this platform will never appear in the middle of other stderr output. However, Rust does not use the C stdio API for writing to stderr, so even on GNU libc, using this option may result in garbled output.

pub fn format(&mut self, format: impl MsgFormat + 'static) -> &mut Self

Set a format for log messages and structured data.

The default is DefaultMsgFormat.

This method wraps the format in an Arc. If your format is alrady wrapped in an Arc, call the format_arc method instead.

Example

use sloggers::Build;
use sloggers::syslog::format::BasicMsgFormat;
use sloggers::syslog::SyslogBuilder;

let logger = SyslogBuilder::new()
    .format(BasicMsgFormat)
    .build()
    .unwrap();

pub fn format_arc(&mut self, format: Arc<dyn MsgFormat>) -> &mut Self

Set a custom format for log messages and structured data.

The default is DefaultMsgFormat.

This method takes the format wrapped in an Arc. Call this if your format is already wrapped in an Arc. If not, call the format method instead.

Example

use sloggers::Build;
use sloggers::syslog::format::BasicMsgFormat;
use sloggers::syslog::SyslogBuilder;
use std::sync::Arc;

let format = Arc::new(BasicMsgFormat);

let logger = SyslogBuilder::new()
    .format_arc(format.clone())
    .build()
    .unwrap();

pub fn level(&mut self, severity: Severity) -> &mut Self

Sets the log level of this logger.

pub fn channel_size(&mut self, channel_size: usize) -> &mut Self

Sets the size of the asynchronous channel of this logger.

pub fn kvfilter(&mut self, parameters: KVFilterParameters) -> &mut Self

Sets KVFilter.

Trait Implementations

impl Build for SyslogBuilder

fn build(&self) -> Result<Logger>

Builds a logger.

impl Debug for SyslogBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SyslogBuilder

fn default() -> Self

Returns the “default value” for a type.