🔊 (config): Emite avisos de opciones como trazas

This commit is contained in:
Manuel Cillero 2026-10-10 22:05:36 +02:00
parent 91f60a420d
commit 3512fed7e0
8 changed files with 81 additions and 85 deletions

View file

@ -103,7 +103,9 @@ pub struct App {
/// *"Australia"*, *"Europe"*, *"Indian"* y *"Pacific"*. Los nombres desconocidos se ignoran con
/// un aviso al arrancar. El grupo *"Etc"*, sólo con `Etc/UTC`, se ofrece siempre, se indique o
/// no; por eso *"Etc"* como único valor deja `Etc/UTC` como la única zona horaria disponible.
/// Si está vacío, o ninguna de las indicadas es válida, se ofrecen todas.
/// Si está vacío se ofrecen todas, y también si ninguna de las indicadas es válida, con un
/// aviso al arrancar. Se avisa igualmente si la región de [`timezone`] queda fuera de las
/// ofrecidas.
///
/// Es el valor por defecto de [`form::SelectTimezone`], que puede cambiarse para un componente
/// concreto con `with_regions()`.
@ -119,6 +121,7 @@ pub struct App {
/// [`TzRegion`]: crate::datetime::TzRegion
/// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone
/// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone
/// [`timezone`]: Self::timezone
pub timezone_regions: String,
/// Orden de las regiones de zonas horarias que se ofrecen para elegir: *"Nearest"*,
/// *"Alphabetical"* o *"Listed"*.
@ -167,7 +170,8 @@ pub struct Log {
pub enabled: bool,
/// Opciones, o combinación de opciones separadas por comas, para filtrar las trazas: *"Error"*,
/// *"Warn"*, *"Info"*, *"Debug"* o *"Trace"*.
/// Ejemplo: *"Error,tower_http=Debug,axum::rejection=trace"*.
/// Ejemplo: *"Error,tower_http=Debug,axum::rejection=trace"*. Si no es válido se usa *"Info"*,
/// con un aviso al arrancar.
pub tracing: String,
/// Muestra los mensajes de traza en el terminal (*"Stdout"*) o los vuelca en archivos con
/// rotación: *"Daily"*, *"Hourly"*, *"Minutely"* o *"Endless"*.

View file

@ -1,4 +1,4 @@
use crate::AutoDefault;
use crate::{AutoDefault, trace};
use serde::{Deserialize, Deserializer};
@ -46,17 +46,7 @@ impl<'de> Deserialize<'de> for LangNegotiation {
"full" => Self::Full,
"noquery" => Self::NoQuery,
"configonly" => Self::ConfigOnly,
_ => {
let default = Self::default();
println!(
concat!(
"\nInvalid value \"{}\" for [app].lang_negotiation. ",
"Using \"{:?}\". Check settings.",
),
raw, default,
);
default
}
_ => trace::warn_invalid_setting("[app].lang_negotiation", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::AutoDefault;
use crate::{AutoDefault, trace};
use serde::{Deserialize, Deserializer};
@ -34,17 +34,7 @@ impl<'de> Deserialize<'de> for LogFormat {
"full" => Self::Full,
"compact" => Self::Compact,
"pretty" => Self::Pretty,
_ => {
let default = Self::default();
println!(
concat!(
"\nInvalid value \"{}\" for [log].format. ",
"Using \"{:?}\". Check settings.",
),
raw, default,
);
default
}
_ => trace::warn_invalid_setting("[log].format", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::AutoDefault;
use crate::{AutoDefault, trace};
use serde::{Deserialize, Deserializer};
@ -9,10 +9,11 @@ use serde::{Deserialize, Deserializer};
/// El valor configurado no distingue entre mayúsculas y minúsculas.
#[derive(AutoDefault, Clone, Copy, Debug, Eq, PartialEq)]
pub enum LogRolling {
/// Escribe las trazas en la salida estándar (sin rotación de archivos).
/// Escribe las trazas en la salida estándar (sin rotación de archivos). Es el valor por
/// defecto.
#[default]
Stdout,
/// Rotación diaria de archivos de traza.
#[default]
Daily,
/// Rotación horaria de archivos de traza.
Hourly,
@ -34,17 +35,7 @@ impl<'de> Deserialize<'de> for LogRolling {
"hourly" => Self::Hourly,
"minutely" => Self::Minutely,
"endless" => Self::Endless,
_ => {
let default = Self::default();
println!(
concat!(
"\nInvalid value \"{}\" for [log].rolling. ",
"Using \"{:?}\". Check settings.",
),
raw, default,
);
default
}
_ => trace::warn_invalid_setting("[log].rolling", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::AutoDefault;
use crate::{AutoDefault, trace};
use serde::{Deserialize, Deserializer};
@ -33,17 +33,7 @@ impl<'de> Deserialize<'de> for StartupBanner {
"small" => Self::Small,
"speed" => Self::Speed,
"starwars" => Self::Starwars,
_ => {
let default = Self::default();
println!(
concat!(
"\nInvalid value \"{}\" for [app].startup_banner. ",
"Using \"{:?}\". Check settings.",
),
raw, default,
);
default
}
_ => trace::warn_invalid_setting("[app].startup_banner", &raw, Self::default()),
};
Ok(result)
}

View file

@ -1,4 +1,4 @@
use crate::AutoDefault;
use crate::{AutoDefault, trace};
use serde::{Deserialize, Deserializer};
@ -40,17 +40,7 @@ impl<'de> Deserialize<'de> for TimezoneOrder {
"nearest" => Self::Nearest,
"alphabetical" => Self::Alphabetical,
"listed" => Self::Listed,
_ => {
let default = Self::default();
println!(
concat!(
"\nInvalid value \"{}\" for [app].timezone_order. ",
"Using \"{:?}\". Check settings.",
),
raw, default,
);
default
}
_ => trace::warn_invalid_setting("[app].timezone_order", &raw, Self::default()),
};
Ok(result)
}

View file

@ -22,29 +22,59 @@ pub use tracing::{debug_span, error_span, info_span, trace_span, warn_span};
use tracing_appender::non_blocking::WorkerGuard;
use tracing_subscriber::EnvFilter;
use std::sync::LazyLock;
use std::fmt;
use std::sync::{LazyLock, Mutex, PoisonError};
// Avisos generados antes de iniciar las trazas. La configuración se lee antes, porque las trazas
// dependen de la sección `[log]`, así que sus avisos se guardan aquí y se emiten al iniciarlas.
static DEFERRED_WARNINGS: Mutex<Vec<String>> = Mutex::new(Vec::new());
// Guarda el aviso de un valor no válido para la opción `key` y devuelve `default`, el valor que se
// usa en su lugar. Lo usan las opciones enumeradas de la configuración al leerse.
pub(crate) fn warn_invalid_setting<T: fmt::Debug>(key: &str, raw: &str, default: T) -> T {
DEFERRED_WARNINGS
.lock()
.unwrap_or_else(PoisonError::into_inner)
.push(format!(
"Invalid value \"{raw}\" for {key}, using \"{default:?}\". Check settings"
));
default
}
/// Trazado y registro de eventos de la aplicación.
///
/// Para aumentar el rendimiento, un hilo dedicado utiliza un sistema de escritura no bloqueante que
/// actúa de forma periódica en lugar de enviar cada traza o evento al instante. Si el programa
/// termina abruptamente (por ejemplo, debido a un `panic!` o a una llamada a `std::process::exit`),
/// es posible que algunas trazas o eventos no se envíen.
/// La escritura no es bloqueante: el código que genera una traza o un evento la deja en una cola y
/// sigue, y un hilo dedicado la escribe en el destino configurado en cuanto la recibe.
///
/// Dado que las trazas o eventos registrados poco antes de un fallo suelen ser cruciales para
/// diagnosticar la causa, `Lazy<WorkerGuard>` garantiza que todos los registros almacenados se
/// envíen antes de finalizar la ejecución.
/// El [`WorkerGuard`] vuelca las trazas pendientes al destruirse, pero un `static` no se destruye
/// nunca, así que al terminar el programa pueden perderse las últimas que quedaran en la cola.
pub(crate) static TRACING: LazyLock<WorkerGuard> = LazyLock::new(|| {
if !global::SETTINGS.log.enabled || cfg!(test) || cfg!(feature = "testing") {
let enabled = global::SETTINGS.log.enabled && !cfg!(test) && !cfg!(feature = "testing");
// Al leer `SETTINGS` en la línea anterior ya se han guardado los avisos de la configuración.
let mut warnings = std::mem::take(
&mut *DEFERRED_WARNINGS
.lock()
.unwrap_or_else(PoisonError::into_inner),
);
if !enabled {
// Tracing desactivado, se instala un subscriber nulo.
tracing::subscriber::set_global_default(tracing::subscriber::NoSubscriber::default())
.expect("Failed to install global NoSubscriber (tracing disabled)");
let (_, guard) = tracing_appender::non_blocking(std::io::sink());
// Los avisos pendientes salen por la salida estándar para que no se pierdan.
for message in warnings {
println!("\n{message}");
}
return guard;
}
let env_filter = EnvFilter::try_new(&global::SETTINGS.log.tracing)
.unwrap_or_else(|_| EnvFilter::new("Info"));
let filter = &global::SETTINGS.log.tracing;
let env_filter = EnvFilter::try_new(filter).unwrap_or_else(|_| {
warnings.push(format!(
"Invalid value \"{filter}\" for [log].tracing, using \"Info\". Check settings"
));
EnvFilter::new("Info")
});
let rolling = global::SETTINGS.log.rolling;
@ -75,5 +105,8 @@ pub(crate) static TRACING: LazyLock<WorkerGuard> = LazyLock::new(|| {
LogFormat::Pretty => subscriber.pretty().init(),
}
for message in warnings {
warn!(target: "pagetop::global", "{message}");
}
guard
});