relay_log/
lib.rs

1//! Error reporting and logging facade for Relay.
2//!
3//! # Setup
4//!
5//! To enable logging, invoke the [`init`] function with [`logging`](LogConfig) and
6//! [`sentry`](SentryConfig) configuration. The configuration implements `serde` traits, so it can
7//! be obtained from configuration files.
8//!
9//! ```
10//! use relay_log::{LogConfig, SentryConfig};
11//!
12//! let log_config = LogConfig {
13//!     enable_backtraces: true,
14//!     ..LogConfig::default()
15//! };
16//!
17//! let sentry_config = SentryConfig {
18//!     enabled: true,
19//!     ..SentryConfig::default()
20//! };
21//!
22//! relay_log::init(&log_config, &sentry_config);
23//! ```
24//!
25//! # Logging
26//!
27//! The basic use of the log crate is through the five logging macros: [`error!`], [`warn!`],
28//! [`info!`], [`debug!`] and [`trace!`] where `error!` represents the highest-priority log messages
29//! and `trace!` the lowest. The log messages are filtered by configuring the log level to exclude
30//! messages with a lower priority. Each of these macros accept format strings similarly to
31//! [`println!`].
32//!
33//! ## Conventions
34//!
35//! Log messages should start lowercase and end without punctuation. Prefer short and precise log
36//! messages over verbose text. Choose the log level according to these rules:
37//!
38//! - [`error!`] for bugs and invalid behavior. This will also be reported to Sentry.
39//! - [`warn!`] for undesirable behavior.
40//! - [`info!`] for messages relevant to the average user.
41//! - [`debug!`] for messages usually relevant to debugging.
42//! - [`trace!`] for full auxiliary information.
43//!
44//! ## Examples
45//!
46//! ```
47//! # let startup_time = std::time::Duration::ZERO;
48//! relay_log::info!(duration = ?startup_time, "startup complete");
49//! ```
50//!
51//! # Error Reporting
52//!
53//! `sentry` is used for error reporting of all messages logged with an ERROR level. To add custom
54//! information, add fields with the `tags.` prefix.
55//!
56//! ## Tags and Fields
57//!
58//! ```
59//! relay_log::error!(
60//!     tags.custom = "value",            // will become a tag in Sentry
61//!     field = "value",                  // will become a context field
62//!     "this message has a custom tag",
63//! );
64//! ```
65//!
66//! ## Logging Error Types
67//!
68//! To log [errors](std::error::Error) to both Sentry and the error stream, use [`error!`] and
69//! assign a reference to the error as `error` field. This formats the error with all its sources,
70//! and ensures the format is suitable for error reporting to Sentry.
71//!
72//! ```
73//! use std::error::Error;
74//! use std::io;
75//!
76//! let custom_error = io::Error::new(io::ErrorKind::Other, "oh no!");
77//! relay_log::error!(error = &custom_error as &dyn Error, "operation failed");
78//! ```
79//!
80//! Alternatively, higher level self-explanatory errors can be passed without an additional message.
81//! They are displayed in the same way in log output, but in Sentry they will display with the error
82//! type as primary title.
83//!
84//! ## Capturing without Logging
85//!
86//! Additionally, errors can be captured without logging.
87//!
88//! ```
89//! use std::io::{Error, ErrorKind};
90//!
91//! let custom_error = Error::new(ErrorKind::Other, "oh no!");
92//! relay_log::capture_error(&custom_error);
93//! ```
94//!
95//! # Testing
96//!
97//! For unit testing, there is a separate initialization macro [`init_test!`] that should be called
98//! at the beginning of test method. It enables test mode of the logger and customizes log levels
99//! for the current crate.
100//!
101//! ```no_run
102//! #[test]
103//! fn test_something() {
104//!     relay_log::init_test!();
105//! }
106//! ```
107
108#![warn(missing_docs)]
109#![doc(
110    html_logo_url = "https://raw.githubusercontent.com/getsentry/relay/master/artwork/relay-icon.png",
111    html_favicon_url = "https://raw.githubusercontent.com/getsentry/relay/master/artwork/relay-icon.png"
112)]
113#![allow(clippy::derive_partial_eq_without_eq)]
114
115#[cfg(feature = "init")]
116mod setup;
117#[cfg(feature = "init")]
118pub use setup::*;
119
120#[cfg(feature = "test")]
121mod test;
122#[cfg(feature = "test")]
123pub use test::*;
124
125mod utils;
126// Expose the minimal log facade.
127#[doc(inline)]
128pub use tracing::{debug, error, info, trace, warn, Level};
129// Expose the minimal error reporting API.
130#[doc(inline)]
131pub use sentry_core::{self as sentry, capture_error, configure_scope, protocol, with_scope, Hub};
132pub use utils::*;
relay_log/lib.rs

relay_log/
lib.rs
