use crate::error::{Failure, Result};
use std::path::{Path, PathBuf};
use tracing::Level;
use tracing_appender::non_blocking::WorkerGuard;
use tracing_appender::rolling::{self, RollingFileAppender};
use tracing_subscriber::layer::SubscriberExt as _;
use tracing_subscriber::util::SubscriberInitExt as _;
const LEVELS: [(&str, Level); 5] = [
("error", Level::ERROR),
("warn", Level::WARN),
("info", Level::INFO),
("debug", Level::DEBUG),
("trace", Level::TRACE),
];
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Rotation {
Daily,
Hourly,
Never,
}
impl Rotation {
#[must_use]
pub fn parse(raw: &str) -> Option<Self> {
match raw.trim().to_ascii_lowercase().as_str() {
"daily" => Some(Self::Daily),
"hourly" => Some(Self::Hourly),
"never" => Some(Self::Never),
_ => None,
}
}
fn as_appender(self) -> rolling::Rotation {
match self {
Self::Daily => rolling::Rotation::DAILY,
Self::Hourly => rolling::Rotation::HOURLY,
Self::Never => rolling::Rotation::NEVER,
}
}
}
#[derive(Debug, Clone)]
pub struct Diagnostics {
pub level: Option<Level>,
pub to_file: bool,
pub directory: PathBuf,
pub rotation: Rotation,
pub retention: usize,
pub colour: bool,
}
impl Diagnostics {
#[must_use]
pub fn to_channel_only(level: Option<Level>, colour: bool) -> Self {
Self {
level,
to_file: false,
directory: PathBuf::new(),
rotation: Rotation::Daily,
retention: 1,
colour,
}
}
}
#[must_use]
pub fn level_for(quiet: bool, verbose: u8, stored: &str) -> Option<Level> {
if quiet {
return None;
}
let floor = LEVELS
.iter()
.position(|(name, _)| *name == stored.trim().to_ascii_lowercase())
.unwrap_or(0);
let index = floor.saturating_add(verbose as usize).min(LEVELS.len() - 1);
LEVELS.get(index).map(|(_, level)| *level)
}
#[must_use]
pub fn name_of(level: Level) -> &'static str {
LEVELS
.iter()
.find(|(_, candidate)| *candidate == level)
.map_or("error", |(name, _)| *name)
}
pub fn build_appender(
directory: &Path,
rotation: Rotation,
retention: usize,
) -> Result<RollingFileAppender> {
std::fs::create_dir_all(directory).map_err(|error| unwritable(directory, &error))?;
let mut builder = rolling::Builder::new()
.rotation(rotation.as_appender())
.filename_prefix(env!("CARGO_PKG_NAME"))
.filename_suffix("log");
builder = builder.max_log_files(retention.max(1));
builder
.build(directory)
.map_err(|error| unwritable(directory, &error))
}
fn unwritable(directory: &Path, cause: &impl std::fmt::Display) -> Failure {
Failure::config(
"log.destination_unwritable",
format!(
"the diagnostic directory `{}` cannot be written to",
directory.display()
),
)
.with_detail("detail", directory.display().to_string())
.with_hint("point `log.to_file` at a writable directory, or set it to false")
.with_cause(cause.to_string())
}
fn scope_of(level: Level) -> tracing_subscriber::filter::Targets {
let own =
tracing_subscriber::filter::Targets::new().with_target(env!("CARGO_CRATE_NAME"), level);
if level >= Level::DEBUG {
own.with_default(level)
} else {
own
}
}
#[derive(Debug, Clone)]
struct Scrubbing<M>(M);
impl<'writer, M: tracing_subscriber::fmt::MakeWriter<'writer>>
tracing_subscriber::fmt::MakeWriter<'writer> for Scrubbing<M>
{
type Writer = ScrubbingWriter<M::Writer>;
fn make_writer(&'writer self) -> Self::Writer {
ScrubbingWriter::new(self.0.make_writer())
}
fn make_writer_for(&'writer self, meta: &tracing::Metadata<'_>) -> Self::Writer {
ScrubbingWriter::new(self.0.make_writer_for(meta))
}
}
#[derive(Debug)]
struct ScrubbingWriter<W: std::io::Write> {
inner: W,
held: Vec<u8>,
}
impl<W: std::io::Write> ScrubbingWriter<W> {
const fn new(inner: W) -> Self {
Self {
inner,
held: Vec::new(),
}
}
fn release(&mut self) -> std::io::Result<()> {
if self.held.is_empty() {
return Ok(());
}
let held = std::mem::take(&mut self.held);
let text = String::from_utf8_lossy(&held);
self.inner.write_all(super::redact::scrub(&text).as_bytes())
}
}
impl<W: std::io::Write> std::io::Write for ScrubbingWriter<W> {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
self.held.extend_from_slice(buf);
Ok(buf.len())
}
fn flush(&mut self) -> std::io::Result<()> {
self.release()?;
self.inner.flush()
}
}
impl<W: std::io::Write> Drop for ScrubbingWriter<W> {
fn drop(&mut self) {
drop(self.release());
}
}
pub fn install(settings: &Diagnostics) -> Result<Option<WorkerGuard>> {
let Some(level) = settings.level else {
return Ok(None);
};
let (writer, guard) = if settings.to_file {
let appender = build_appender(&settings.directory, settings.rotation, settings.retention)?;
let (writer, guard) = tracing_appender::non_blocking(appender);
(Some(writer), Some(guard))
} else {
(None, None)
};
let file_layer = writer.map(|writer| {
tracing_subscriber::fmt::layer()
.with_ansi(false)
.with_writer(Scrubbing(writer))
});
let channel_layer = tracing_subscriber::fmt::layer()
.with_ansi(settings.colour)
.with_writer(Scrubbing(std::io::stderr));
tracing_subscriber::registry()
.with(scope_of(level))
.with(channel_layer)
.with(file_layer)
.try_init()
.map_err(|error| {
Failure::config(
"log.already_installed",
"the auxiliary channel was already installed for this process",
)
.with_cause(error.to_string())
})?;
Ok(guard)
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(Debug, Clone, Default)]
struct Collected(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);
impl Collected {
fn text(&self) -> String {
String::from_utf8_lossy(&self.0.lock().expect("not poisoned")).into_owned()
}
}
impl std::io::Write for Collected {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
self.0.lock().expect("not poisoned").extend_from_slice(buf);
Ok(buf.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
#[test]
fn no_secret_reaches_a_destination_through_this_channel() {
use std::io::Write as _;
let collected = Collected::default();
let secrets = [
"opening mysql://app:hunter2@db.internal:3306/shop",
"sending CREATE USER 'app'@'%' IDENTIFIED BY 'hunter2'",
"read password=hunter2 from the file",
];
for line in secrets {
let mut writer = ScrubbingWriter::new(collected.clone());
writer.write_all(line.as_bytes()).expect("collected");
drop(writer);
}
let written = collected.text();
assert!(!written.contains("hunter2"), "written: {written}");
assert!(written.contains("db.internal"), "the host is not a secret");
assert!(written.contains("CREATE USER"), "the shape still reads");
}
#[test]
fn a_line_split_across_writes_is_examined_whole() {
use std::io::Write as _;
let collected = Collected::default();
let line = "opening mysql://app:hunter2@db.internal/shop";
let mut writer = ScrubbingWriter::new(collected.clone());
for chunk in line.as_bytes().chunks(3) {
writer.write_all(chunk).expect("collected");
}
drop(writer);
let written = collected.text();
assert!(!written.contains("hunter2"), "written: {written}");
assert!(written.contains("db.internal"));
}
#[test]
fn an_ordinary_line_passes_through_unchanged() {
use std::io::Write as _;
let collected = Collected::default();
let line = "connected to db.internal:3306 in 12ms\n";
let mut writer = ScrubbingWriter::new(collected.clone());
writer.write_all(line.as_bytes()).expect("collected");
drop(writer);
assert_eq!(collected.text(), line);
}
#[test]
fn every_destination_this_channel_installs_is_wrapped() {
let source = include_str!("tracing.rs");
let wrapped = concat!("with_", "writer(Scrubbing(");
let any_writer = concat!("with_", "writer(");
let wrapped_count = source.matches(wrapped).count();
let writer_count = source.matches(any_writer).count();
assert_eq!(
wrapped_count, 2,
"the screen and the file are the two destinations, and both are wrapped"
);
assert_eq!(
writer_count, wrapped_count,
"a destination was installed without the wrapper, so lines reach it \
with whatever they carried"
);
}
#[test]
fn silence_wins_over_everything_stored() {
assert_eq!(level_for(true, 0, "trace"), None);
}
#[test]
fn the_stored_setting_decides_when_no_mark_was_given() {
assert_eq!(level_for(false, 0, "error"), Some(Level::ERROR));
assert_eq!(level_for(false, 0, "info"), Some(Level::INFO));
}
#[test]
fn each_repetition_of_the_mark_raises_the_detail_one_step() {
assert_eq!(level_for(false, 1, "error"), Some(Level::WARN));
assert_eq!(level_for(false, 2, "error"), Some(Level::INFO));
assert_eq!(level_for(false, 3, "error"), Some(Level::DEBUG));
assert_eq!(level_for(false, 4, "error"), Some(Level::TRACE));
}
#[test]
fn raising_the_detail_stops_at_the_loudest_level() {
assert_eq!(level_for(false, 200, "error"), Some(Level::TRACE));
}
#[test]
fn an_unreadable_stored_level_falls_back_to_the_quietest() {
assert_eq!(level_for(false, 0, "shout"), Some(Level::ERROR));
}
#[test]
fn every_rotation_word_the_registry_publishes_is_read() {
assert_eq!(Rotation::parse("daily"), Some(Rotation::Daily));
assert_eq!(Rotation::parse("HOURLY"), Some(Rotation::Hourly));
assert_eq!(Rotation::parse(" never "), Some(Rotation::Never));
assert_eq!(Rotation::parse("weekly"), None);
}
#[test]
fn a_diagnostic_file_is_created_where_it_was_asked_for() {
let directory = tempfile::tempdir().expect("scratch directory");
let target = directory.path().join("diagnostics");
build_appender(&target, Rotation::Daily, 3).expect("writable");
assert!(target.is_dir(), "the destination must exist afterwards");
}
#[test]
fn the_set_of_files_never_passes_the_configured_retention() {
const RETENTION: usize = 2;
let directory = tempfile::tempdir().expect("scratch directory");
let target = directory.path().join("diagnostics");
std::fs::create_dir_all(&target).expect("creates");
let prefix = env!("CARGO_PKG_NAME");
for day in 1..=5 {
std::fs::write(target.join(format!("{prefix}.2020-01-0{day}.log")), b"old")
.expect("writes an earlier turn");
}
assert_eq!(
kept(&target, prefix),
5,
"five turns are on disk to begin with"
);
let appender = build_appender(&target, Rotation::Daily, RETENTION).expect("writable");
std::io::Write::write_all(&mut { appender }, b"now\n").expect("writes");
assert!(
kept(&target, prefix) <= RETENTION,
"the retention of {RETENTION} left {} files behind",
kept(&target, prefix)
);
}
fn kept(directory: &std::path::Path, prefix: &str) -> usize {
std::fs::read_dir(directory)
.expect("a readable directory")
.flatten()
.filter(|entry| {
entry
.file_name()
.to_str()
.is_some_and(|name| name.starts_with(prefix) && name.ends_with("log"))
})
.count()
}
#[test]
fn a_destination_that_cannot_be_written_is_refused_by_configuration() {
let directory = tempfile::tempdir().expect("scratch directory");
let blocker = directory.path().join("not-a-directory");
std::fs::write(&blocker, b"x").expect("writes");
let failure = build_appender(&blocker.join("inside"), Rotation::Daily, 1)
.expect_err("a file is not a directory");
assert_eq!(failure.code(), "log.destination_unwritable");
assert_eq!(failure.exit_number().code(), 4);
}
#[test]
fn a_library_underneath_is_kept_off_the_quiet_channel() {
for level in [Level::ERROR, Level::WARN, Level::INFO] {
let scope = scope_of(level);
assert!(
scope.would_enable(env!("CARGO_CRATE_NAME"), &level),
"the product must still be heard at `{}`",
name_of(level)
);
assert!(
!scope.would_enable("mysql_async::conn::routines::prepare", &level),
"the driver must not write to the channel at `{}`",
name_of(level)
);
}
}
#[test]
fn asking_for_detail_lets_the_libraries_back_in() {
for level in [Level::DEBUG, Level::TRACE] {
assert!(
scope_of(level).would_enable("mysql_async::conn::routines::prepare", &Level::ERROR),
"the driver must be heard again at `{}`",
name_of(level)
);
}
}
#[test]
fn a_silent_channel_installs_nothing_at_all() {
let settings = Diagnostics::to_channel_only(None, false);
assert!(install(&settings).expect("silence never fails").is_none());
}
#[test]
fn every_level_has_a_published_name() {
for (name, level) in LEVELS {
assert_eq!(name_of(level), name);
}
}
}