log v0.4.0 Release Notes

Release Date: 2017-12-24 // over 6 years ago
  • ๐Ÿš€ The changes in this release include cleanup of some obscure functionality and a more robust public ๐ŸŒฒ API designed to support bridges to other logging systems, and provide more flexibility to new ๐Ÿ”‹ features in the future.

    Compatibility

    ๐Ÿš€ Vast portions of the Rust ecosystem use the 0.3.x release series of log, and we don't want to force โฌ†๏ธ the community to go through the pain of upgrading every crate to 0.4.x at the exact same time. Along ๐Ÿš€ with 0.4.0, we've published a new 0.3.9 release which acts as a "shim" over 0.4.0. This will allow crates using either version to coexist without losing messages from one side or the other.

    ๐ŸŒฒ There is one caveat - a log message generated by a crate using 0.4.x but consumed by a logging implementation using 0.3.x will not have a file name or module path. Applications affected by this โฌ†๏ธ can upgrade their logging implementations to one using 0.4.x to avoid losing this information. The other direction does not lose any information, fortunately!

    TL;DR Libraries should feel comfortable upgrading to 0.4.0 without treating that as a breaking โšก๏ธ change. Applications may need to update their logging implementation (e.g. env-logger) to a newer ๐Ÿ”– version using log 0.4.x to avoid losing module and file information.

    ๐Ÿ†• New

    • 0๏ธโƒฃ The crate is now no_std by default.
    • Level and LevelFilter now implement Serialize and Deserialize when the serde feature is enabled.
    • ๐Ÿ“‡ The Record and Metadata types can now be constructed by third-party code via a builder API.
    • ๐Ÿ†“ The logger free function returns a reference to the logger implementation. This, along with the ability to construct Records, makes it possible to bridge from another logging framework to this one without digging into the private internals of the crate. The standard error! warn!, etc, macros now exclusively use the public API of the crate rather than "secret" internal APIs.
    • ๐ŸŒฒ Log::flush has been added to allow crates to tell the logging implementation to ensure that all "in flight" log events have been persisted. This can be used, for example, just before an application exits to ensure that asynchronous log sinks finish their work.

    โœ‚ Removed

    • ๐Ÿšš The shutdown and shutdown_raw functions have been removed. Supporting shutdown significantly complicated the implementation and imposed a performance cost on each logging operation.
    • ๐Ÿšš The log_panics function and its associated nightly Cargo feature have been removed. Use the log-panics instead.

    ๐Ÿ”„ Changed

    • ๐Ÿšš The Log prefix has been removed from type names. For example, LogLevelFilter is now LevelFilter, and LogRecord is now Record.
    • The MaxLogLevelFilter object has been removed in favor of a set_max_level free function.
    • ๐Ÿ†“ The set_logger free functions have been restructured. The logger is now directly passed to the functions rather than a closure which returns the logger. set_logger now takes a &'static Log and is usable in no_std contexts in place of the old set_logger_raw. set_boxed_logger is a convenience function which takes a Box<Log> but otherwise acts like set_logger. It requires the std feature.
    • ๐Ÿ‘ The file and module_path values in Record no longer have the 'static lifetime to support integration with other logging frameworks that don't provide a 'static lifetime for the equivalent values.
    • ๐Ÿ‘ The file, line, and module_path values in Record are now Options to support integration with other logging frameworks that don't provide those values.

    In the Future

    • We're looking to add support for structured logging - the inclusion of extra key-value pairs of information in a log event in addition to the normal string message. This should be able to be added in a backwards compatible manner to the 0.4.x series when the design is worked out.