Crate relay_log

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

protocol

The current latest sentry protocol version.

sentry

This crate provides the core of the Sentry SDK, which can be used to log events and errors.

Macros

debug

Constructs an event at the debug level.

error

Constructs an event at the error level.

info

Constructs an event at the info level.

init_test

Initialize the logger for testing.

trace

Constructs an event at the trace level.

warn

Constructs an event at the warn level.

Structs

FormatParseError

The logging format parse error.

Hub

The central object that can manage scopes and clients.

Level

Describes the level of verbosity of a span or event.

LevelParseError

The logging level parse error.

LogConfig

Controls the logging system.

SentryConfig

Controls internal reporting to Sentry.

Enums

LogFormat

Controls the log format.

Functions

backtrace_enabled

Returns true if backtrace printing is enabled.

capture_error

Captures a std::error::Error.

configure_scope

Invokes a function that can modify the current scope.

ensure_error

Logs an error to the configured logger or stderr if not yet configured.

init

Initialize the logging system and reporting to Sentry.

with_scope

Temporarily pushes a scope for a single call optionally reconfiguring it.