🔊 (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. # 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. # 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. # da igual escribirla en mayúsculas o minúsculas.
# Se aplica a anónimos y a usuarios sin zona horaria propia, # Se aplica a anónimos y a usuarios sin zona horaria propia,
# y a todos si 'timezone_per_user' es false. # y a todos si 'timezone_per_user' es false.
timezone_regions = "" # Regiones de zonas horarias que se ofrecen, separadas por timezone_regions = "" # Regiones de las zonas horarias que se ofrecen, separadas por
# comas (p. ej. "Europe, America"): "Africa", "America", # comas (p. ej. "Europe, America"), elegidas entre "Africa",
# "Antarctica", "Arctic", "Asia", "Atlantic", "Australia", # "America", "Antarctica", "Arctic", "Asia", "Atlantic",
# "Europe", "Indian" y "Pacific". "Etc" (Etc/UTC) se ofrece # "Australia", "Europe", "Indian" y "Pacific". "Etc" (Etc/UTC)
# siempre. Vacío -> todas. Los nombres desconocidos se ignoran # se ofrece siempre. Si está vacío se ofrecen todas. Los nombres
# con un aviso al arrancar. No cambia las zonas ya asignadas a # desconocidos se ignoran con un aviso al arrancar; si ninguno
# los usuarios (las conservan), sólo las nuevas elecciones. # es válido se ofrecen todas, y se avisa también si la región de
# Es el valor por defecto del selector de zona horaria; la # 'timezone' queda fuera de las ofrecidas. No cambia las zonas
# aplicación puede cambiarlo en un formulario concreto. # 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: timezone_order = "Nearest" # Orden de esas regiones al elegir zona horaria:
# "Nearest" -> la del sitio primero, si tiene región, y # "Nearest" -> la del sitio primero, si tiene región, y
# luego por cercanía de su desfase horario. # 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. enabled = true # Activa (true) o desactiva (false) las trazas.
tracing = "Info" # Filtro de trazas: "Error", "Warn", "Info", "Debug" o tracing = "Info" # Filtro de trazas: "Error", "Warn", "Info", "Debug" o
# "Trace", o combinaciones separadas por comas por módulo, # "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: rolling = "Stdout" # Salida de las trazas:
# "Stdout" -> terminal, sin archivos. # "Stdout" -> terminal, sin archivos.
# "Daily", "Hourly", "Minutely" -> archivos con rotación. # "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 /// *"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 /// 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. /// 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 /// Es el valor por defecto de [`form::SelectTimezone`], que puede cambiarse para un componente
/// concreto con `with_regions()`. /// concreto con `with_regions()`.
@ -119,6 +121,7 @@ pub struct App {
/// [`TzRegion`]: crate::datetime::TzRegion /// [`TzRegion`]: crate::datetime::TzRegion
/// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone /// [`CurrentUser::timezone()`]: crate::auth::CurrentUser::timezone
/// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone /// [`form::SelectTimezone`]: crate::base::component::form::SelectTimezone
/// [`timezone`]: Self::timezone
pub timezone_regions: String, pub timezone_regions: String,
/// Orden de las regiones de zonas horarias que se ofrecen para elegir: *"Nearest"*, /// Orden de las regiones de zonas horarias que se ofrecen para elegir: *"Nearest"*,
/// *"Alphabetical"* o *"Listed"*. /// *"Alphabetical"* o *"Listed"*.
@ -167,7 +170,8 @@ pub struct Log {
pub enabled: bool, pub enabled: bool,
/// Opciones, o combinación de opciones separadas por comas, para filtrar las trazas: *"Error"*, /// Opciones, o combinación de opciones separadas por comas, para filtrar las trazas: *"Error"*,
/// *"Warn"*, *"Info"*, *"Debug"* o *"Trace"*. /// *"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, pub tracing: String,
/// Muestra los mensajes de traza en el terminal (*"Stdout"*) o los vuelca en archivos con /// Muestra los mensajes de traza en el terminal (*"Stdout"*) o los vuelca en archivos con
/// rotación: *"Daily"*, *"Hourly"*, *"Minutely"* o *"Endless"*. /// rotación: *"Daily"*, *"Hourly"*, *"Minutely"* o *"Endless"*.

View file

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

View file

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

View file

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

View file

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

View file

@ -1,4 +1,4 @@
use crate::AutoDefault; use crate::{AutoDefault, trace};
use serde::{Deserialize, Deserializer}; use serde::{Deserialize, Deserializer};
@ -40,17 +40,7 @@ impl<'de> Deserialize<'de> for TimezoneOrder {
"nearest" => Self::Nearest, "nearest" => Self::Nearest,
"alphabetical" => Self::Alphabetical, "alphabetical" => Self::Alphabetical,
"listed" => Self::Listed, "listed" => Self::Listed,
_ => { _ => trace::warn_invalid_setting("[app].timezone_order", &raw, Self::default()),
let default = Self::default();
println!(
concat!(
"\nInvalid value \"{}\" for [app].timezone_order. ",
"Using \"{:?}\". Check settings.",
),
raw, default,
);
default
}
}; };
Ok(result) 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_appender::non_blocking::WorkerGuard;
use tracing_subscriber::EnvFilter; 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. /// Trazado y registro de eventos de la aplicación.
/// ///
/// Para aumentar el rendimiento, un hilo dedicado utiliza un sistema de escritura no bloqueante que /// La escritura no es bloqueante: el código que genera una traza o un evento la deja en una cola y
/// actúa de forma periódica en lugar de enviar cada traza o evento al instante. Si el programa /// sigue, y un hilo dedicado la escribe en el destino configurado en cuanto la recibe.
/// 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.
/// ///
/// Dado que las trazas o eventos registrados poco antes de un fallo suelen ser cruciales para /// El [`WorkerGuard`] vuelca las trazas pendientes al destruirse, pero un `static` no se destruye
/// diagnosticar la causa, `Lazy<WorkerGuard>` garantiza que todos los registros almacenados se /// nunca, así que al terminar el programa pueden perderse las últimas que quedaran en la cola.
/// envíen antes de finalizar la ejecución.
pub(crate) static TRACING: LazyLock<WorkerGuard> = LazyLock::new(|| { 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 desactivado, se instala un subscriber nulo.
tracing::subscriber::set_global_default(tracing::subscriber::NoSubscriber::default()) tracing::subscriber::set_global_default(tracing::subscriber::NoSubscriber::default())
.expect("Failed to install global NoSubscriber (tracing disabled)"); .expect("Failed to install global NoSubscriber (tracing disabled)");
let (_, guard) = tracing_appender::non_blocking(std::io::sink()); 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; return guard;
} }
let env_filter = EnvFilter::try_new(&global::SETTINGS.log.tracing) let filter = &global::SETTINGS.log.tracing;
.unwrap_or_else(|_| EnvFilter::new("Info")); 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; let rolling = global::SETTINGS.log.rolling;
@ -75,5 +105,8 @@ pub(crate) static TRACING: LazyLock<WorkerGuard> = LazyLock::new(|| {
LogFormat::Pretty => subscriber.pretty().init(), LogFormat::Pretty => subscriber.pretty().init(),
} }
for message in warnings {
warn!(target: "pagetop::global", "{message}");
}
guard guard
}); });