0.2.7 |
|
---|---|
0.2.6 |
|
0.2.2 |
|
0.1.7 |
|
0.1.0 |
|
#74 in #aptos
30 downloads per month
Used in 88 crates
(53 directly)
95KB
2K
SLoC
This crates provides an API for logging.
Instrumenting with Logs
Basic instrumenting with Logs
A set of logging macros (info!
, error!
, warn!
, debug!
, and trace!
) is provided for
emitting logs at different levels. All of these macros support the addition of providing
structured data along with a formatted text message. For guidelines on which level to use,
see the coding guidelines.
The below examples do no type checking for structured log fields, and instead just serialize whatever is given.
use aptos_logger::info;
let world = "world!";
// Formatted message, similar to `printf!`
info!("hello {}", world);
// => '{"level":"info", "message": "hello world!"}'
// Structured data can be logged using the format 'key = value'
// where value implements Serialize. This can be used for indexing and search later.
let value1 = 5;
info!(key1 = value1);
// => '{"level":"info", "data": {"key1": 5}}'
// You can even set multiple key/value pairs and a format message together
let value2 = false;
info!(key1 = value1, key2 = value2, "hello {}", world);
// => '{"level":"info", "data": {"key1": 5, "key2": false}, "message": "hello world!"}'
// Structured data can also use `Display` or `Debug` outputs instead.
// Using the sigil `?` for debug and `%` for display.
let value1 = 5;
info!(debug_key = ?value1, display_key = %value1);
// => '{"level":"info", "data": {"display_key": 5, "debug_key": 5}}'
Note
Arguments used in a formatted message are not captured and included as structured data.
Everything after the format string literal e.g. "hello {}"
are only used in the format string.
Preferred instrumenting with Logs (Typed Schemas)
The Schema
trait can be used to implement typed logging schemas. This can either be
implemented by hand or derived using the Schema
derive proc-macro, implementing the Schema
trait for the struct as well as providing setters for all fields.
use aptos_logger::{info, Schema};
#[derive(Schema)]
struct LogSchema<'a> {
// Log using this type's Serialize impl
a: usize,
// Log using this type's Debug impl
#[schema(debug)]
b: Option<Vec<bool>>,
// Log using this type's Display impl
#[schema(display)]
c: Option<&'a str>,
}
let log = LogSchema { a: 5, b: None, c: None };
// Automatic setters are named based on the field names, and handle `Option`
// None fields will be ignored
info!(log.c("radiant"));
// => '{"level":"info", "data": { "a": 5, "c": "radiant"}}'
#[derive(Schema)]
struct OtherSchema<'a> {
val: Option<&'a str>
}
let log = LogSchema { a: 5, b: None, c: None };
let other = OtherSchema { val: None };
// Schemas can be combined
info!(
other.val("awesome"), // First schema
log // Second schema has fields added to it all
);
// => '{"level":"info", "data": { "a": 5, "val":"awesome"}}'
let log = LogSchema { a: 5, b: None, c: None };
let other = OtherSchema { val: None };
// Schemas can be combined with one off fields and messages like above
info!(
other.val("awesome"), // First schema
log, // Second schema has fields added to it all
new_field = "new", // Basic structured fields
"Message: {}", // Format messages
"Some message" // Format message fields (not added to indexed fields)
);
// => {"level":"info", "message": "Message: Some message",
// "data": { "a": 5, "val":"awesome", "new_field": "new"}}'
Sampling logs
Sometimes logging a large amount of data is expensive. In order to log information only part
of the time, we've added a sample!
macro that's configurable on how often we want to execute some code.
SampleRate
determines how often the sampled statement will occur.
use aptos_logger::{info, sample, sample::{SampleRate, Sampling}};
use std::time::Duration;
// Sampled based on frequency of events, log only every 2 logs
sample!(SampleRate::Frequency(2), info!("Long log"));
// Sampled based on time passed, log at most once a minute
sample!(SampleRate::Duration(Duration::from_secs(60)), info!("Long log"));
Configuration
In order for logs to be captured and emitted a Logger needs to be instantiated. This can be
done by using the Logger
type:
use aptos_logger::{Level, Logger};
Logger::builder().level(Level::Info).build();
Dependencies
~9–23MB
~292K SLoC