Crate log_hz 

Log Hz

A logging library that provides macros for logging at a throttled rate.

This crate was inspired by experience with ROS_LOG_THROTTLE from ROS 1.

In robotics applications we often have loops running at fixed (often very high) rates. In these loops log messages can be very useful for debugging, but can also quickly flood the log with duplicate information. Throttled logging macros that prevent excess log spam can be very useful.

use log_hz::*;

fn get_io_pin() -> Result<u8, String> {
  Err("Your IO Device Isn't Connected!".to_string())
}

fn main() {
  loop {
    let io_pin = get_io_pin();
    match io_pin {
      Ok(pin) => {
        debug_hz!(1.0, "IO Pin State: {}", pin);
      },
      Err(e) => {
        error_hz!(1.0, "Failed to get IO Pin: {}", e);
      }
    }
  }
}

This crate provides the following throttled logging macros, matching their equivalents from the log crate: error_hz!, warn_hz!, info_hz!, debug_hz!, and trace_hz!.

The rate is specified in Hz, and can be any expression that can be compile time cast to a f32 with as f32.

use log_hz::*;

fn main() {
  // Rate can't be dynamic:
  let rate = 1.0;
  // info_hz!(rate, "Hello, world!"); // This won't compile

  // Instead, use a literal or something that can be compile time cast to a f32
  info_hz!(1.0, "Hello, world!");
  info_hz!(1.0f32, "Hello, world!");
  info_hz!(1, "Hello, world!");

  const fn load_rate() -> f32 { 1.0 }
  info_hz!(load_rate(), "Hello, world!");

  static RATE: f32 = 1.0;
  info_hz!(RATE, "Hello, world!");
}

It also re-exports all of the log crate’s macros and functions, so you can use them as you normally would without needing to import it separately:

// Cargo.toml only contains `log_hz = "0.1.0"`, no need to import `log` separately
use log_hz::*;

fn main() {
  // This comes from the log crate
  error!("This is an error message");
  // This comes from the log_hz crate
  error_hz!(1.0, "This is an error message that will only log once per second");
}

This crate is compatible with all the amazing loggers that the log crate is compatible with. An abbreviated list include:

• env_logger - Extremely common logger for getting started with Enviroment variable configuration using RUST_LOG.
• simple_logger - Good for simple logging needs, manually configured in code.
• flexi_logger - Good for combining multiple loggers, and logging to multiple destinations.
• log4rs - Rust equivalent of the popular Java logging framework, or log4cxx the C++ equivalent.
• slog - Big logging ecosystem with a ton of power.
• testing_logger - If you want to unit test your log messages.

You will need to initialize a logger before log messages from this crate will be visible. See the documentation for the logger you are using for more information.

Note: This crate uses std::time::Instant to track time, which is not available in no_std environments. If you’re interested in alternative timing backends for this crate, feel free to open an issue or PR to add them behind features.

Macros

debug

Logs a message at the debug level.

debug_hz

Log a message at Level::Debug at a throttled rate, first call will always log.

error

Logs a message at the error level.

error_hz

Log a message at Level::Error at a throttled rate, first call will always log.

info

Logs a message at the info level.

info_hz

Log a message at Level::Info at a throttled rate, first call will always log.

log

The standard logging macro.

log_enabled

Determines if a message logged at the specified level in that module will be logged.

log_hz

Log a message at the specified level at a throttled rate, first call will always log.

trace

Logs a message at the trace level.

trace_hz

Log a message at Level::Trace at a throttled rate, first call will always log.

warn

Logs a message at the warn level.

warn_hz

Log a message at Level::Warn at a throttled rate, first call will always log.

Structs

Metadata

Metadata about a log message.

MetadataBuilder

Builder for Metadata.

ParseLevelError

The type returned by from_str when the string doesn’t match any of the log levels.

Record

The “payload” of a log message.

RecordBuilder

Builder for Record.

SetLoggerError

The type returned by set_logger if set_logger has already been called.

Enums

Level

An enum representing the available verbosity levels of the logger.

LevelFilter

An enum representing the available verbosity level filters of the logger.

Constants

STATIC_MAX_LEVEL

The statically resolved maximum log level.

Traits

Log

A trait encapsulating the operations required of a logger.

Functions

logger

Returns a reference to the logger.

max_level

Returns the current maximum log level.

set_logger

Sets the global logger to a &'static Log.

set_logger_racy^⚠

A thread-unsafe version of set_logger.

set_max_level

Sets the global maximum log level.

set_max_level_racy^⚠

A thread-unsafe version of set_max_level.