use std::fmt;
use serde::{Deserialize, Serialize};
use time::{UtcOffset, format_description::well_known::Rfc3339};
use tracing::{Event, Subscriber};
use tracing_subscriber::{
EnvFilter,
fmt::{
self as tracing_fmt, FmtContext, FormattedFields,
format::{FormatEvent, JsonFields, Writer},
time::{FormatTime, OffsetTime},
},
layer::SubscriberExt,
registry::LookupSpan,
util::SubscriberInitExt,
};
mod error;
pub use error::LoggingError;
const RUST_LOG_ENV: &str = "RUST_LOG";
pub const MAX_TRACING_SERVICE_NAME_LENGTH: usize = 128;
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct TracingConfig {
service_name: String,
json: bool,
env_filter: Option<String>,
time_zone: LogTimeZone,
}
impl TracingConfig {
pub fn new(service_name: impl Into<String>) -> Result<Self, LoggingError> {
let service_name = service_name.into().trim().to_owned();
validate_service_name(&service_name)?;
Ok(Self {
service_name,
json: false,
env_filter: None,
time_zone: LogTimeZone::Utc,
})
}
#[must_use]
pub fn with_json(mut self, json: bool) -> Self {
self.json = json;
self
}
#[must_use]
pub fn with_env_filter(mut self, env_filter: impl Into<String>) -> Self {
self.env_filter = Some(env_filter.into().trim().to_owned());
self
}
#[must_use]
pub const fn with_time_zone(mut self, time_zone: LogTimeZone) -> Self {
self.time_zone = time_zone;
self
}
#[must_use]
pub fn service_name(&self) -> &str {
&self.service_name
}
#[must_use]
pub const fn json(&self) -> bool {
self.json
}
#[must_use]
pub fn env_filter(&self) -> Option<&str> {
self.env_filter.as_deref()
}
#[must_use]
pub const fn time_zone(&self) -> LogTimeZone {
self.time_zone
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum LogTimeZone {
#[default]
Utc,
Local,
}
impl LogTimeZone {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Utc => "utc",
Self::Local => "local",
}
}
}
struct ServiceEventFormat<T> {
service_name: String,
json: bool,
timer: T,
}
impl<S, T> FormatEvent<S, JsonFields> for ServiceEventFormat<T>
where
S: Subscriber + for<'lookup> LookupSpan<'lookup>,
T: FormatTime,
{
fn format_event(
&self,
context: &FmtContext<'_, S, JsonFields>,
mut writer: Writer<'_>,
event: &Event<'_>,
) -> fmt::Result {
let mut timestamp = String::new();
self.timer.format_time(&mut Writer::new(&mut timestamp))?;
let metadata = event.metadata();
let mut fields = EventFields::default();
event.record(&mut fields);
let mut spans = Vec::new();
if let Some(scope) = context.event_scope() {
for span in scope.from_root() {
let extensions = span.extensions();
let cached = extensions
.get::<FormattedFields<JsonFields>>()
.ok_or(fmt::Error)?;
let mut fields: serde_json::Map<String, serde_json::Value> =
serde_json::from_str(&cached.fields).map_err(|_| fmt::Error)?;
fields.insert("name".into(), span.name().into());
fields.insert("service_name".into(), self.service_name.clone().into());
spans.push(fields);
}
}
if self.json {
#[derive(Serialize)]
struct JsonEvent<'a> {
timestamp: &'a str,
level: &'a str,
service_name: &'a str,
target: &'a str,
fields: &'a serde_json::Map<String, serde_json::Value>,
#[serde(skip_serializing_if = "Option::is_none")]
span: Option<&'a serde_json::Map<String, serde_json::Value>>,
#[serde(skip_serializing_if = "Option::is_none")]
spans: Option<&'a [serde_json::Map<String, serde_json::Value>]>,
}
let output = serde_json::to_string(&JsonEvent {
timestamp: ×tamp,
level: metadata.level().as_str(),
service_name: &self.service_name,
target: metadata.target(),
fields: &fields.0,
span: spans.last(),
spans: (!spans.is_empty()).then_some(spans.as_slice()),
})
.map_err(|_| fmt::Error)?;
writeln!(writer, "{output}")
} else {
if !timestamp.is_empty() {
write!(writer, "{timestamp} ")?;
}
write!(writer, "{:>5} ", metadata.level())?;
for span in spans {
write!(writer, "{}{{", span["name"].as_str().ok_or(fmt::Error)?)?;
write_text_fields(&mut writer, &span, Some("name"))?;
writer.write_str("}: ")?;
}
write!(writer, "{}: ", metadata.target())?;
write_text_fields(&mut writer, &fields.0, None)?;
writeln!(writer, " service_name={:?}", self.service_name)
}
}
}
fn write_text_fields(
writer: &mut Writer<'_>,
fields: &serde_json::Map<String, serde_json::Value>,
skip: Option<&str>,
) -> fmt::Result {
let mut separator = "";
for (key, value) in fields {
if Some(key.as_str()) == skip {
continue;
}
write!(writer, "{separator}{key}={value}")?;
separator = " ";
}
Ok(())
}
#[derive(Default)]
struct EventFields(serde_json::Map<String, serde_json::Value>);
impl tracing::field::Visit for EventFields {
fn record_f64(&mut self, field: &tracing::field::Field, value: f64) {
self.0.insert(field.name().into(), value.into());
}
fn record_i64(&mut self, field: &tracing::field::Field, value: i64) {
self.0.insert(field.name().into(), value.into());
}
fn record_u64(&mut self, field: &tracing::field::Field, value: u64) {
self.0.insert(field.name().into(), value.into());
}
fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
self.0.insert(field.name().into(), value.into());
}
fn record_str(&mut self, field: &tracing::field::Field, value: &str) {
self.0.insert(field.name().into(), value.into());
}
fn record_bytes(&mut self, field: &tracing::field::Field, value: &[u8]) {
self.0.insert(field.name().into(), value.into());
}
fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn fmt::Debug) {
let name = field.name().strip_prefix("r#").unwrap_or(field.name());
self.0.insert(name.into(), format!("{value:?}").into());
}
}
pub fn tracing_layer<S>(
config: &TracingConfig,
) -> Result<
tracing_fmt::Layer<
S,
JsonFields,
impl FormatEvent<S, JsonFields> + Send + Sync + 'static + use<S>,
>,
LoggingError,
>
where
S: Subscriber + for<'lookup> LookupSpan<'lookup>,
{
let timer = match config.time_zone {
LogTimeZone::Utc => OffsetTime::new(UtcOffset::UTC, Rfc3339),
LogTimeZone::Local => {
OffsetTime::local_rfc_3339().map_err(LoggingError::LocalTimeOffset)?
}
};
Ok(tracing_fmt::layer()
.with_ansi(false)
.fmt_fields(JsonFields::new())
.event_format(ServiceEventFormat {
service_name: config.service_name.clone(),
json: config.json,
timer,
}))
}
pub fn tracing_filter(config: &TracingConfig) -> Result<EnvFilter, LoggingError> {
env_filter_from(config, std::env::var(RUST_LOG_ENV).ok())
}
pub fn init(config: &TracingConfig) -> Result<(), LoggingError> {
tracing_subscriber::registry()
.with(tracing_filter(config)?)
.with(tracing_layer(config)?)
.try_init()?;
Ok(())
}
fn env_filter_from(
config: &TracingConfig,
env_value: Option<String>,
) -> Result<EnvFilter, LoggingError> {
if let Some(value) = env_value
.as_deref()
.map(str::trim)
.filter(|value| !value.is_empty())
{
return Ok(EnvFilter::try_new(value)?);
}
if let Some(value) = config
.env_filter
.as_deref()
.map(str::trim)
.filter(|value| !value.is_empty())
{
return Ok(EnvFilter::try_new(value)?);
}
Ok(EnvFilter::try_new("info,tower_http=info")?)
}
fn validate_service_name(value: &str) -> Result<(), LoggingError> {
if value.is_empty()
|| value.len() > MAX_TRACING_SERVICE_NAME_LENGTH
|| !value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.' | b':'))
{
return Err(LoggingError::InvalidServiceName);
}
Ok(())
}
#[cfg(test)]
mod tests {
use std::{
io,
sync::{Arc, Mutex},
};
use tracing_subscriber::{fmt::MakeWriter, layer::SubscriberExt};
use super::{
JsonFields, LogTimeZone, LoggingError, ServiceEventFormat, TracingConfig, env_filter_from,
tracing_fmt,
};
use crate::result::{ClassifyError, ErrorKind};
#[test]
fn builds_default_filter_from_service_name() {
let filter = env_filter_from(&TracingConfig::new("example_service").unwrap(), None)
.expect("filter should be valid");
assert_eq!(filter.to_string(), "tower_http=info,info");
}
#[test]
fn rejects_invalid_service_name() {
let result = TracingConfig::new("bad service");
assert!(matches!(result, Err(LoggingError::InvalidServiceName)));
}
#[test]
fn env_filter_overrides_config_filter() {
let filter = env_filter_from(
&TracingConfig::new("example_service")
.unwrap()
.with_env_filter("=bad"),
Some("example_service=debug".to_owned()),
)
.expect("environment filter should override config filter");
assert_eq!(filter.to_string(), "example_service=debug");
}
#[test]
fn tracing_config_defaults_to_utc_timestamps() {
let config = TracingConfig::new("example_service").unwrap();
assert_eq!(config.time_zone(), LogTimeZone::Utc);
assert_eq!(
config.with_time_zone(LogTimeZone::Local).time_zone(),
LogTimeZone::Local
);
assert_eq!(LogTimeZone::Utc.as_str(), "utc");
assert_eq!(LogTimeZone::Local.as_str(), "local");
}
#[test]
fn rejects_invalid_explicit_filter_without_env_override() {
let result = env_filter_from(
&TracingConfig::new("example_service")
.unwrap()
.with_env_filter("=bad"),
None,
);
let error = result.expect_err("invalid filter should fail");
assert!(matches!(&error, LoggingError::InvalidFilter(_)));
assert!(!format!("{error:?}").contains("=bad"));
}
#[test]
fn rejects_invalid_env_filter() {
let result = env_filter_from(
&TracingConfig::new("example_service").unwrap(),
Some("=bad".to_owned()),
);
assert!(matches!(result, Err(LoggingError::InvalidFilter(_))));
}
#[test]
fn logging_errors_have_stable_classification() {
let service_name = LoggingError::InvalidServiceName.error_descriptor();
assert_eq!(service_name.kind(), ErrorKind::Validation);
assert_eq!(service_name.code().as_str(), "tracing_service_name_invalid");
let error = env_filter_from(&TracingConfig::new("service").unwrap(), Some("=bad".into()))
.expect_err("invalid filter must fail");
assert_eq!(error.error_kind(), ErrorKind::Validation);
assert_eq!(error.error_code().as_str(), "tracing_filter_invalid");
}
#[derive(Clone, Default)]
struct Buffer(Arc<Mutex<Vec<u8>>>);
struct BufferWriter(Arc<Mutex<Vec<u8>>>);
impl io::Write for BufferWriter {
fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
self.0
.lock()
.map_err(|_| io::Error::other("test output lock poisoned"))?
.extend_from_slice(bytes);
Ok(bytes.len())
}
fn flush(&mut self) -> io::Result<()> {
Ok(())
}
}
impl<'writer> MakeWriter<'writer> for Buffer {
type Writer = BufferWriter;
fn make_writer(&'writer self) -> Self::Writer {
BufferWriter(Arc::clone(&self.0))
}
}
impl Buffer {
fn output(&self) -> String {
let bytes = self
.0
.lock()
.expect("test output lock should not be poisoned")
.clone();
String::from_utf8(bytes).expect("tracing output should be UTF-8")
}
}
fn emit_events() {
tracing::info!(
event_field = 1,
bytes = &[0u8, 127, 255][..],
flag = true,
ratio = 1.5,
"outside span"
);
let span = tracing::info_span!("request", span_field = 2);
let _entered = span.enter();
tracing::info!(event_field = 3, "inside span");
}
#[test]
fn public_layer_owns_config_and_composes_with_independent_filters_and_writers() {
use std::sync::atomic::{AtomicUsize, Ordering};
use crate::logging::{TracingConfig, tracing_layer};
use tracing_subscriber::{EnvFilter, Layer, layer::Context};
struct CountEvents(Arc<AtomicUsize>);
impl<S: tracing::Subscriber> Layer<S> for CountEvents {
fn on_event(&self, _: &tracing::Event<'_>, _: Context<'_, S>) {
self.0.fetch_add(1, Ordering::Relaxed);
}
}
for json in [false, true] {
let output = Buffer::default();
let events = Arc::new(AtomicUsize::new(0));
let config = TracingConfig::new("composed_service")
.unwrap()
.with_json(json);
let logs = tracing_layer(&config)
.unwrap()
.with_writer(output.clone())
.with_filter(EnvFilter::new("warn"));
drop(config);
let subscriber = tracing_subscriber::registry()
.with(logs)
.with(CountEvents(events.clone()));
tracing::subscriber::with_default(subscriber, || {
tracing::info!("other layer only");
tracing::warn!("both layers");
});
assert_eq!(events.load(Ordering::Relaxed), 2);
let text = output.output();
assert_eq!(text.lines().count(), 1);
assert!(text.contains("both layers"));
assert!(text.contains("composed_service"));
if json {
let event: serde_json::Value = serde_json::from_str(&text).unwrap();
assert_eq!(event["service_name"], "composed_service");
assert_eq!(event["level"], "WARN");
}
}
}
#[test]
fn configured_service_name_is_present_on_text_events_and_spans() {
let output = Buffer::default();
let subscriber = tracing_subscriber::registry().with(
tracing_fmt::layer()
.without_time()
.with_ansi(false)
.with_target(false)
.with_writer(output.clone())
.fmt_fields(JsonFields::new())
.event_format(ServiceEventFormat {
service_name: "example_service".to_owned(),
json: false,
timer: (),
}),
);
tracing::subscriber::with_default(subscriber, emit_events);
let lines = output
.output()
.lines()
.map(str::to_owned)
.collect::<Vec<_>>();
assert_eq!(lines.len(), 2);
assert!(
lines
.iter()
.all(|line| line.contains("service_name=\"example_service\""))
);
assert!(lines[1].matches("service_name=\"example_service\"").count() >= 2);
}
#[test]
fn configured_service_name_is_present_on_json_events_and_spans() {
let output = Buffer::default();
let event_format = ServiceEventFormat {
service_name: "example_service".to_owned(),
json: true,
timer: (),
};
let subscriber = tracing_subscriber::registry().with(
tracing_fmt::layer()
.with_ansi(false)
.with_target(false)
.with_writer(output.clone())
.fmt_fields(JsonFields::new())
.event_format(event_format),
);
tracing::subscriber::with_default(subscriber, emit_events);
let lines = output
.output()
.lines()
.map(str::to_owned)
.collect::<Vec<_>>();
assert_eq!(lines.len(), 2);
let event: serde_json::Value = serde_json::from_str(&lines[0]).unwrap();
assert_eq!(event["fields"]["bytes"], serde_json::json!([0, 127, 255]));
assert_eq!(event["fields"]["flag"], true);
assert_eq!(event["fields"]["ratio"], 1.5);
assert!(
lines
.iter()
.all(|line| line.contains(r#""service_name":"example_service""#))
);
assert!(
lines[1]
.matches(r#""service_name":"example_service""#)
.count()
>= 2
);
}
#[test]
fn span_updates_replace_fields_without_growing_the_buffer_in_both_formats() {
use tracing_subscriber::{fmt::FormattedFields, registry::LookupSpan};
for json in [false, true] {
let output = Buffer::default();
let subscriber = tracing_subscriber::registry().with(
tracing_fmt::layer()
.with_writer(output.clone())
.fmt_fields(JsonFields::new())
.event_format(ServiceEventFormat {
service_name: "configured_service".to_owned(),
json,
timer: (),
}),
);
let subscriber = Arc::new(subscriber);
tracing::subscriber::with_default(subscriber.clone(), || {
let parent = tracing::info_span!("parent", service_name = "incorrect");
let _parent = parent.enter();
let span = tracing::info_span!(
"child",
counter = 0,
service_name = "incorrect",
note = tracing::field::Empty
);
for counter in 1..=10_000 {
span.record("counter", counter);
}
span.record("note", "quoted\"\n中文");
span.record("service_name", "still_incorrect");
let stored = subscriber.span(&span.id().unwrap()).unwrap();
let extensions = stored.extensions();
let fields = &extensions
.get::<FormattedFields<JsonFields>>()
.unwrap()
.fields;
assert!(
fields.len() < 150,
"span fields must hold only current values"
);
assert_eq!(fields.matches("\"counter\"").count(), 1);
drop(extensions);
let _entered = span.enter();
tracing::info!("updated");
});
let text = output.output();
if !json {
assert_eq!(text.matches("counter=").count(), 1);
assert!(text.contains("counter=10000"));
assert!(!text.contains("incorrect"));
assert_eq!(text.lines().count(), 1);
continue;
}
let event: serde_json::Value = serde_json::from_str(&text).unwrap();
assert_eq!(event["service_name"], "configured_service");
assert_eq!(event["span"]["counter"], 10_000);
assert_eq!(event["span"]["note"], "quoted\"\n中文");
assert_eq!(event["span"]["service_name"], "configured_service");
assert!(
event["spans"]
.as_array()
.unwrap()
.iter()
.all(|span| span["service_name"] == "configured_service")
);
}
}
}