Expand description
Error reporting and logging facade for Relay.
§Setup
To enable logging, invoke the init
function with logging
and
sentry
configuration. The configuration implements serde
traits, so it can
be obtained from configuration files.
use relay_log::{LogConfig, SentryConfig};
let log_config = LogConfig {
enable_backtraces: true,
..LogConfig::default()
};
let sentry_config = SentryConfig {
enabled: true,
..SentryConfig::default()
};
relay_log::init(&log_config, &sentry_config);
§Logging
The basic use of the log crate is through the five logging macros: error!
, warn!
,
info!
, debug!
and trace!
where error!
represents the highest-priority log messages
and trace!
the lowest. The log messages are filtered by configuring the log level to exclude
messages with a lower priority. Each of these macros accept format strings similarly to
println!
.
§Conventions
Log messages should start lowercase and end without punctuation. Prefer short and precise log messages over verbose text. Choose the log level according to these rules:
error!
for bugs and invalid behavior. This will also be reported to Sentry.warn!
for undesirable behavior.info!
for messages relevant to the average user.debug!
for messages usually relevant to debugging.trace!
for full auxiliary information.
§Examples
relay_log::info!(duration = ?startup_time, "startup complete");
§Error Reporting
sentry
is used for error reporting of all messages logged with an ERROR level. To add custom
information, add fields with the tags.
prefix.
§Tags and Fields
relay_log::error!(
tags.custom = "value", // will become a tag in Sentry
field = "value", // will become a context field
"this message has a custom tag",
);
§Logging Error Types
To log errors to both Sentry and the error stream, use error!
and
assign a reference to the error as error
field. This formats the error with all its sources,
and ensures the format is suitable for error reporting to Sentry.
use std::error::Error;
use std::io;
let custom_error = io::Error::new(io::ErrorKind::Other, "oh no!");
relay_log::error!(error = &custom_error as &dyn Error, "operation failed");
Alternatively, higher level self-explanatory errors can be passed without an additional message. They are displayed in the same way in log output, but in Sentry they will display with the error type as primary title.
§Capturing without Logging
Additionally, errors can be captured without logging.
use std::io::{Error, ErrorKind};
let custom_error = Error::new(ErrorKind::Other, "oh no!");
relay_log::capture_error(&custom_error);
§Testing
For unit testing, there is a separate initialization macro init_test!
that should be called
at the beginning of test method. It enables test mode of the logger and customizes log levels
for the current crate.
#[test]
fn test_something() {
relay_log::init_test!();
}
Modules§
- The current latest sentry protocol version.
- This crate provides the core of the Sentry SDK, which can be used to log events and errors.
Macros§
- Constructs an event at the debug level.
- Constructs an event at the error level.
- Constructs an event at the info level.
- Initialize the logger for testing.
- Constructs an event at the trace level.
- Constructs an event at the warn level.
Structs§
- The central object that can manages scopes and clients.
- Describes the level of verbosity of a span or event.
- The logging level parse error.
- Controls the logging system.
- Controls internal reporting to Sentry.
Enums§
- Controls the log format.
Functions§
- Returns
true
if backtrace printing is enabled. - Captures a
std::error::Error
. - Invokes a function that can modify the current scope.
- Logs an error to the configured logger or
stderr
if not yet configured. - Initialize the logging system and reporting to Sentry.
- Temporarily pushes a scope for a single call optionally reconfiguring it.