🔊 (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

@ -15,6 +15,10 @@
# variables de entorno: el resto de opciones sólo se leen de estos ficheros.
#
# Las opciones comentadas no tienen valor por defecto; se muestran con un valor de ejemplo.
#
# En las opciones del núcleo con valores fijos ("Full", "Nearest"...) da igual escribir el valor en
# mayúsculas o minúsculas; uno no válido se sustituye por el valor por defecto, con un aviso al
# arrancar.
# ==================================================================================================
@ -37,15 +41,18 @@ timezone = "UTC" # Zona horaria del sitio (IANA: "UTC", "Euro
# da igual escribirla en mayúsculas o minúsculas.
# Se aplica a anónimos y a usuarios sin zona horaria propia,
# y a todos si 'timezone_per_user' es false.
timezone_regions = "" # Regiones de zonas horarias que se ofrecen, separadas por
# comas (p. ej. "Europe, America"): "Africa", "America",
# "Antarctica", "Arctic", "Asia", "Atlantic", "Australia",
# "Europe", "Indian" y "Pacific". "Etc" (Etc/UTC) se ofrece
# siempre. Vacío -> todas. Los nombres desconocidos se ignoran
# con un aviso al arrancar. No cambia las zonas ya asignadas a
# los usuarios (las conservan), sólo las nuevas elecciones.
# Es el valor por defecto del selector de zona horaria; la
# aplicación puede cambiarlo en un formulario concreto.
timezone_regions = "" # Regiones de las zonas horarias que se ofrecen, separadas por
# comas (p. ej. "Europe, America"), elegidas entre "Africa",
# "America", "Antarctica", "Arctic", "Asia", "Atlantic",
# "Australia", "Europe", "Indian" y "Pacific". "Etc" (Etc/UTC)
# se ofrece siempre. Si está vacío se ofrecen todas. Los nombres
# desconocidos se ignoran con un aviso al arrancar; si ninguno
# es válido se ofrecen todas, y se avisa también si la región de
# 'timezone' queda fuera de las ofrecidas. No cambia las zonas
# ya asignadas a los usuarios (las conservan), sólo las nuevas
# elecciones. Es el valor por defecto del selector de zona
# horaria; la aplicación puede cambiarlo en un formulario
# concreto.
timezone_order = "Nearest" # Orden de esas regiones al elegir zona horaria:
# "Nearest" -> la del sitio primero, si tiene región, y
# luego por cercanía de su desfase horario.
@ -73,7 +80,8 @@ bootsier_static_dir = "" # Igual que el anterior, para los archivos e
enabled = true # Activa (true) o desactiva (false) las trazas.
tracing = "Info" # Filtro de trazas: "Error", "Warn", "Info", "Debug" o
# "Trace", o combinaciones separadas por comas por módulo,
# p. ej. "Info,pagetop=Debug,sqlx=Warn".
# p. ej. "Info,pagetop=Debug,sqlx=Warn". Si no es válido se
# usa "Info", con un aviso al arrancar.
rolling = "Stdout" # Salida de las trazas:
# "Stdout" -> terminal, sin archivos.
# "Daily", "Hourly", "Minutely" -> archivos con rotación.

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
});