Struct Builder

pub struct Builder { /* private fields */ }

A builder type for Logger.

You can use this builder to register endpoints, set default endpoints, control the levels of logging messages emitted, and filter messages based on module name.

A Builder is consumed by calling Builder::init() or Builder::try_init() to build and automatically initialize the logger, or by calling Builder::build() to build the logger for manual initialization or nesting within another logger. After you call any of these methods, you can no longer call any of them on that same builder.

Implementations

impl Builder

pub fn new() -> Self

Create a new Builder.

By default, no endpoints are registered, the maximum log level is set to Off, and no module name filtering is done.

pub fn endpoint<E>(&mut self, endpoint: E) -> &mut Self

where E: TryInto<Endpoint>, <E as TryInto<Endpoint>>::Error: Into<Error>,

Register an endpoint.

log_fastly::Logger::builder()
    .max_level(log::LevelFilter::Trace)
    .endpoint("my_endpoint")
    .init();
log::info!(target: "my_endpoint", "Hello");

pub fn endpoint_level<E>( &mut self, endpoint: E, level: LevelFilter, ) -> &mut Self

where E: TryInto<Endpoint>, <E as TryInto<Endpoint>>::Error: Into<Error>,

Register an endpoint and set the maximum logging level for its messages.

log_fastly::Logger::builder()
    .max_level(log::LevelFilter::Trace)
    .endpoint_level("debug_endpoint", log::LevelFilter::Debug)
    .init();
log::info!(target: "debug_endpoint", "This will be written to debug_endpoint...");
log::trace!(target: "debug_endpoint", "...but this won't be...");

pub fn default_endpoint<E>(&mut self, endpoint: E) -> &mut Self

where E: TryInto<Endpoint>, <E as TryInto<Endpoint>>::Error: Into<Error>,

Set the default endpoint for all messages.

The default endpoint is used when the logging statement does not use the target: "endpoint" syntax.

This overrides any previous default endpoints, set either by this method or by Builder::default_level_endpoint().

log_fastly::Logger::builder()
    .max_level(log::LevelFilter::Info)
    .default_level_endpoint("error_only", log::Level::Error)
    .default_endpoint("my_endpoint")
    .endpoint("other_endpoint")
    .init();
log::info!("This will be written to my_endpoint...");
log::error!("...and this will too");
log::warn!(target: "other_endpoint", "This will go to other_endpoint, though");

pub fn default_level_endpoint<E>( &mut self, endpoint: E, level: Level, ) -> &mut Self

where E: TryInto<Endpoint>, <E as TryInto<Endpoint>>::Error: Into<Error>,

Set the default endpoint for all messages of the given level.

The default endpoint is used when the logging statement does not use the target: "endpoint" syntax.

This overrides any previous default endpoints set for this level, either by this method or by Builder::default_endpoint().

log_fastly::Logger::builder()
    .max_level(log::LevelFilter::Info)
    .default_endpoint("my_endpoint")
    .default_level_endpoint("error_only", log::Level::Error)
    .endpoint("other_endpoint")
    .init();
log::info!("This will be written to my_endpoint...");
log::error!("...but this will be written to error_only");
log::error!(target: "other_endpoint", "This will go to other_endpoint, though");

pub fn max_level(&mut self, level: LevelFilter) -> &mut Self

Set the maximum logging level for all messages.

No messages that exceed this level will be emitted, even if a higher level is set for a specific endpoint or module name.

Note: The default level is LevelFilter::Off, which emits no logging at all. You’ll want to change this for most configurations.

log_fastly::Builder::new()
    .max_level(log::LevelFilter::Warn)
    .endpoint_level("my_endpoint", log::LevelFilter::Info)
    .init();
log::warn!(target: "my_endpoint", "This will be written to my_endpoint...");
log::info!(target: "my_endpoint", "...but this won't");

pub fn filter_module(&mut self, regex: &str, level: LevelFilter) -> &mut Self

Set a logging level for modules whose names match the given regular expression.

By default, logging statements in any module are emitted if their level is within Builder::max_level() and the level for their target endpoint. If you configure filters with this method, the name of the module calling the logging statement must also match one of the patterns, and be within the filter’s specified level.

mod my_module {
    pub fn do_a_thing() {
        log::warn!("This won't be written, because this module's max level is Error...");
        log::error!("...but this will be written");
    }
}

log_fastly::Logger::builder()
    .max_level(log::LevelFilter::Info)
    .default_endpoint("my_endpoint")
    .filter_module("my_module", log::LevelFilter::Error)
    .init();
log::info!("This won't be written, because it's not in my_module");
// This will only emit one log message, because "my_app$" doesn't match, and
// "my_app::my_module" is limited to Error
my_module::do_a_thing();

pub fn echo_stdout(&mut self, enabled: bool) -> &mut Self

Set whether all log messages should be echoed to stdout (false by default).

If this is set to true, all logging statements will write the message to stdout in addition to the specified endpoint. This is particularly useful when debugging with Compute Log Tailing.

pub fn echo_stderr(&mut self, enabled: bool) -> &mut Self

Set whether all log messages should be echoed to stderr (false by default).

If this is set to true, all logging statements will write the message to stderr in addition to the specified endpoint. This is particularly useful when debugging with Compute Log Tailing.

pub fn init(&mut self)

Build the logger and initialize it as the global logger.

log_fastly::Builder::new()
    .default_endpoint("my_endpoint")
    .init();
log::info!("Hello");

Panics

This may panic for any of the reasons that Builder::try_init() would return an error.

pub fn try_init(&mut self) -> Result<(), Error>

Build the logger and initialize it as the global logger.

This will fail with an Err value if a global logger is already initialized, or for any of the reasons that Builder::build() can fail.

log_fastly::Builder::new()
    .default_endpoint("my_endpoint")
    .try_init()
    .unwrap();
log::info!("Hello");

pub fn build(&mut self) -> Result<Logger, Error>

Build a Logger, using up this builder.

This is mainly useful if you want to manually initialize the logger, or nest it within another log::Log implementation.

This will fail with an Err value if:

• This builder has already been used to build a Logger.

• Any of the registered endpoint names are invalid.

• Any of the module name filters set by Builder::filter_module() have invalid regex syntax.

let logger = log_fastly::Builder::new()
    .default_endpoint("my_endpoint")
    .build()
    .unwrap();
log::set_boxed_logger(Box::new(logger)).unwrap();

Trait Implementations

impl Debug for Builder

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

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.