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

• dashboard
  This module provides the functionality for subscribing to the logs stream and delivering it to the external consumers through the [tokio::sync::broadcast] channel.
• 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

• Hub
  The central object that can manages 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.