tracing_microjson/

lib.rs

//! A tracing JSON layer with zero serialization framework dependencies.
//!
//! Drop-in replacement for tracing-subscriber's `json` feature, producing
//! identical output format without pulling in serde/serde_json/tracing-serde.
//!
//! # Quick start
//!
//! ```rust
//! use tracing_microjson::JsonLayer;
//! use tracing_subscriber::prelude::*;
//!
//! tracing_subscriber::registry()
//!     .with(JsonLayer::new(std::io::stderr))
//!     .init();
//! ```
//!
//! # Configuration
//!
//! [`JsonLayer`] uses a builder pattern. All options have sensible defaults —
//! only override what you need.
//!
//! ```rust
//! # use tracing_microjson::JsonLayer;
//! # use tracing_subscriber::prelude::*;
//! tracing_subscriber::registry()
//!     .with(
//!         JsonLayer::new(std::io::stderr)
//!             .with_target(false)
//!             .with_file(true)
//!             .with_line_number(true)
//!             .flatten_event(true)
//!             .without_time(),
//!     )
//!     .init();
//! ```
//!
//! | Method | Default | Effect |
//! |---|---|---|
//! | [`JsonLayer::with_target`] | `true` | Include the event target (module path) |
//! | [`JsonLayer::with_file`] | `false` | Include the source filename |
//! | [`JsonLayer::with_line_number`] | `false` | Include the source line number |
//! | [`JsonLayer::with_thread_ids`] | `false` | Include the thread ID |
//! | [`JsonLayer::with_thread_names`] | `false` | Include the thread name |
//! | [`JsonLayer::flatten_event`] | `false` | Flatten event fields to the top level instead of nesting under `"fields"` |
//! | [`JsonLayer::with_timer`] | [`SystemTimestamp`] | Use a custom [`FormatTime`] implementation for timestamps |
//! | [`JsonLayer::without_time`] | — | Disable timestamps entirely |
//!
//! # Output format
//!
//! Every event is written as a single JSON line. The fields present depend on
//! the configuration above and whether the event occurs inside a span:
//!
//! ```text
//! {"timestamp":"…","level":"INFO","fields":{"message":"hello"},"target":"my_app","span":{"name":"req"},"spans":[{"name":"req"}]}
//! ```
//!
//! - `timestamp` — RFC 3339 with microsecond precision in UTC by default.
//!   Customisable via [`with_timer`](JsonLayer::with_timer) or disabled with
//!   [`without_time`](JsonLayer::without_time).
//! - `level` — always present (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`).
//! - `fields` — event fields, nested under `"fields"` by default. With
//!   [`flatten_event(true)`](JsonLayer::flatten_event) they appear at the top
//!   level instead.
//! - `target` — module path, present when [`with_target`](JsonLayer::with_target)
//!   is `true`.
//! - `filename` / `line_number` — source location, present when enabled via
//!   [`with_file`](JsonLayer::with_file) / [`with_line_number`](JsonLayer::with_line_number).
//! - `threadId` / `threadName` — thread info, present when enabled via
//!   [`with_thread_ids`](JsonLayer::with_thread_ids) / [`with_thread_names`](JsonLayer::with_thread_names).
//! - `span` — the innermost active span (if any).
//! - `spans` — all active spans from root to leaf (if any).

use std::io::Write;
use std::time::SystemTime;
use tracing_core::{Event, Subscriber};
use tracing_subscriber::Layer;
use tracing_subscriber::fmt::format::Writer as FmtWriter;
use tracing_subscriber::layer::Context;
use tracing_subscriber::registry::LookupSpan;

pub use tracing_subscriber::fmt::time::FormatTime;

mod visitor;

#[cfg(feature = "_bench_internals")]
pub mod writer;
#[cfg(not(feature = "_bench_internals"))]
mod writer;

use visitor::JsonVisitor;
use writer::JsonWriter;

/// A timestamp formatter that produces RFC 3339 timestamps with microsecond
/// precision in UTC (e.g. `2026-02-20T12:00:00.000000Z`).
///
/// This is the default timer used by [`JsonLayer`]. It uses a hand-written
/// formatter for minimal overhead — no chrono or time crate required.
pub struct SystemTimestamp;

impl FormatTime for SystemTimestamp {
    fn format_time(&self, w: &mut FmtWriter<'_>) -> std::fmt::Result {
        w.write_str(&format_timestamp(SystemTime::now()))
    }
}

// Extension type stored in span data
struct SpanFields(String);

/// A [`tracing_subscriber::Layer`] that formats events as JSON lines.
///
/// See the [crate-level docs](crate) for configuration options and output
/// format details.
pub struct JsonLayer<W, T = SystemTimestamp> {
    make_writer: W,
    timer: T,
    display_target: bool,
    display_filename: bool,
    display_line_number: bool,
    display_thread_id: bool,
    display_thread_name: bool,
    flatten_event: bool,
}

impl<W> JsonLayer<W>
where
    W: for<'w> tracing_subscriber::fmt::MakeWriter<'w> + 'static,
{
    /// Create a new `JsonLayer` that writes JSON lines to `make_writer`.
    ///
    /// Accepts anything implementing [`tracing_subscriber::fmt::MakeWriter`],
    /// e.g. `std::io::stderr` or `std::io::stdout`.
    pub fn new(make_writer: W) -> Self {
        Self {
            make_writer,
            timer: SystemTimestamp,
            display_target: true,
            display_filename: false,
            display_line_number: false,
            display_thread_id: false,
            display_thread_name: false,
            flatten_event: false,
        }
    }
}

impl<W, T> JsonLayer<W, T>
where
    W: for<'w> tracing_subscriber::fmt::MakeWriter<'w> + 'static,
{
    /// Set whether the `target` field (module path) is included in output.
    ///
    /// Default: **`true`**.
    pub fn with_target(mut self, display_target: bool) -> Self {
        self.display_target = display_target;
        self
    }

    /// Set whether the `filename` field is included in output.
    ///
    /// Default: **`false`**.
    pub fn with_file(mut self, display_filename: bool) -> Self {
        self.display_filename = display_filename;
        self
    }

    /// Set whether the `line_number` field is included in output.
    ///
    /// Default: **`false`**.
    pub fn with_line_number(mut self, display_line: bool) -> Self {
        self.display_line_number = display_line;
        self
    }

    /// Set whether the `threadId` field is included in output.
    ///
    /// Default: **`false`**.
    pub fn with_thread_ids(mut self, display_thread_id: bool) -> Self {
        self.display_thread_id = display_thread_id;
        self
    }

    /// Set whether the `threadName` field is included in output.
    ///
    /// Default: **`false`**.
    pub fn with_thread_names(mut self, display_thread_name: bool) -> Self {
        self.display_thread_name = display_thread_name;
        self
    }

    /// Set whether event fields are flattened to the top level of the JSON
    /// object instead of being nested under a `"fields"` key.
    ///
    /// Default: **`false`** (fields are nested).
    pub fn flatten_event(mut self, flatten: bool) -> Self {
        self.flatten_event = flatten;
        self
    }

    /// Use a custom [`FormatTime`] implementation for timestamps.
    ///
    /// This replaces the default [`SystemTimestamp`] formatter. Any type
    /// implementing [`FormatTime`] can be used, including those from
    /// `tracing-subscriber` such as `Uptime` and `ChronoUtc`.
    ///
    /// Pass `()` to disable timestamps entirely (equivalent to
    /// [`without_time`](Self::without_time)).
    pub fn with_timer<T2: FormatTime>(self, timer: T2) -> JsonLayer<W, T2> {
        JsonLayer {
            make_writer: self.make_writer,
            timer,
            display_target: self.display_target,
            display_filename: self.display_filename,
            display_line_number: self.display_line_number,
            display_thread_id: self.display_thread_id,
            display_thread_name: self.display_thread_name,
            flatten_event: self.flatten_event,
        }
    }

    /// Disable timestamps in the output.
    ///
    /// This is a convenience for `self.with_timer(())`.
    pub fn without_time(self) -> JsonLayer<W, ()> {
        self.with_timer(())
    }
}

impl<S, W, T> Layer<S> for JsonLayer<W, T>
where
    S: Subscriber + for<'a> LookupSpan<'a>,
    W: for<'w> tracing_subscriber::fmt::MakeWriter<'w> + 'static,
    T: FormatTime + 'static,
{
    fn on_new_span(
        &self,
        attrs: &tracing_core::span::Attributes<'_>,
        id: &tracing_core::span::Id,
        ctx: Context<'_, S>,
    ) {
        let span = match ctx.span(id) {
            Some(s) => s,
            None => return,
        };
        let mut jw = JsonWriter::new();
        let mut visitor = JsonVisitor::new(&mut jw);
        attrs.record(&mut visitor);
        span.extensions_mut().insert(SpanFields(jw.into_string()));
    }

    fn on_record(
        &self,
        id: &tracing_core::span::Id,
        values: &tracing_core::span::Record<'_>,
        ctx: Context<'_, S>,
    ) {
        let span = match ctx.span(id) {
            Some(s) => s,
            None => return,
        };
        let mut ext = span.extensions_mut();
        if let Some(fields) = ext.get_mut::<SpanFields>() {
            let has_existing = !fields.0.is_empty();
            let mut jw = JsonWriter::continuing(&fields.0);
            let mut visitor = if has_existing {
                JsonVisitor::continuing(&mut jw)
            } else {
                JsonVisitor::new(&mut jw)
            };
            values.record(&mut visitor);
            fields.0 = jw.into_string();
        }
    }

    fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) {
        let mut jw = JsonWriter::new();

        jw.obj_start();

        // timestamp (absent when timer is `()` / `without_time()`)
        let mut ts_buf = String::new();
        {
            let mut fmt_writer = FmtWriter::new(&mut ts_buf);
            let _ = self.timer.format_time(&mut fmt_writer);
        }
        let wrote_timestamp = !ts_buf.is_empty();
        if wrote_timestamp {
            jw.key("timestamp");
            jw.val_str(&ts_buf);
        }

        // level
        if wrote_timestamp {
            jw.comma();
        }
        jw.key("level");
        jw.val_str(&event.metadata().level().to_string());

        if self.flatten_event {
            // Event fields flattened to top level
            let mut visitor = JsonVisitor::continuing(&mut jw);
            event.record(&mut visitor);
        } else {
            // Event fields nested under "fields"
            jw.comma();
            jw.key("fields");
            jw.obj_start();
            let mut visitor = JsonVisitor::new(&mut jw);
            event.record(&mut visitor);
            jw.obj_end();
        }

        // target
        if self.display_target {
            jw.comma();
            jw.key("target");
            jw.val_str(event.metadata().target());
        }

        // filename
        if self.display_filename
            && let Some(file) = event.metadata().file()
        {
            jw.comma();
            jw.key("filename");
            jw.val_str(file);
        }

        // line_number
        if self.display_line_number
            && let Some(line) = event.metadata().line()
        {
            jw.comma();
            jw.key("line_number");
            jw.val_u64(line as u64);
        }

        // thread ID
        if self.display_thread_id {
            jw.comma();
            jw.key("threadId");
            jw.val_str(&format!("{:?}", std::thread::current().id()));
        }

        // thread name
        if self.display_thread_name {
            jw.comma();
            jw.key("threadName");
            if let Some(name) = std::thread::current().name() {
                jw.val_str(name);
            } else {
                jw.val_str("");
            }
        }

        // current span and spans list
        if let Some(scope) = ctx.event_scope(event) {
            let spans: Vec<_> = scope.collect();

            // "span" = innermost (first in iterator = closest to current)
            if let Some(leaf) = spans.first() {
                jw.comma();
                jw.key("span");
                jw.obj_start();
                jw.key("name");
                jw.val_str(leaf.name());
                let ext = leaf.extensions();
                if let Some(fields) = ext.get::<SpanFields>()
                    && !fields.0.is_empty()
                {
                    jw.comma();
                    jw.raw(&fields.0);
                }
                jw.obj_end();
            }

            // "spans" = all spans from root to leaf
            jw.comma();
            jw.key("spans");
            jw.arr_start();
            for (i, span) in spans.iter().rev().enumerate() {
                if i > 0 {
                    jw.comma();
                }
                jw.obj_start();
                jw.key("name");
                jw.val_str(span.name());
                let ext = span.extensions();
                if let Some(fields) = ext.get::<SpanFields>()
                    && !fields.0.is_empty()
                {
                    jw.comma();
                    jw.raw(&fields.0);
                }
                jw.obj_end();
            }
            jw.arr_end();
        }

        jw.obj_end();
        jw.finish_line();

        let line = jw.into_string();
        let mut writer = self.make_writer.make_writer();
        let _ = writer.write_all(line.as_bytes());
    }
}

/// Format a `SystemTime` as RFC 3339 with microsecond precision in UTC.
/// e.g. "2026-02-20T12:00:00.000000Z"
fn format_timestamp(t: SystemTime) -> String {
    let dur = t.duration_since(SystemTime::UNIX_EPOCH).unwrap_or_default();
    let secs = dur.as_secs();
    let micros = dur.subsec_micros();

    // Decompose Unix seconds into date/time components
    let (year, month, day, hour, min, sec) = secs_to_datetime(secs);

    format!("{year:04}-{month:02}-{day:02}T{hour:02}:{min:02}:{sec:02}.{micros:06}Z")
}

/// Convert Unix seconds to (year, month, day, hour, min, sec) in UTC.
fn secs_to_datetime(secs: u64) -> (u64, u64, u64, u64, u64, u64) {
    let sec = secs % 60;
    let mins = secs / 60;
    let min = mins % 60;
    let hours = mins / 60;
    let hour = hours % 24;
    let days = hours / 24;

    // Compute year, month, day from days since epoch (1970-01-01)
    let (year, month, day) = days_to_ymd(days);

    (year, month, day, hour, min, sec)
}

fn days_to_ymd(days: u64) -> (u64, u64, u64) {
    // Using the algorithm from civil_from_days (Howard Hinnant's date algorithms)
    let z = days + 719468;
    let era = z / 146097;
    let doe = z % 146097;
    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let d = doy - (153 * mp + 2) / 5 + 1;
    let m = if mp < 10 { mp + 3 } else { mp - 9 };
    let y = if m <= 2 { y + 1 } else { y };
    (y, m, d)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Helper: write a string through val_str and return the raw buffer content.
    fn val_str_output(s: &str) -> String {
        let mut jw = JsonWriter::new();
        jw.val_str(s);
        jw.into_string()
    }

    #[test]
    fn test_val_str_basic() {
        assert_eq!(val_str_output("hello"), r#""hello""#);
        assert_eq!(val_str_output("say \"hi\""), r#""say \"hi\"""#);
        assert_eq!(val_str_output("back\\slash"), r#""back\\slash""#);
        assert_eq!(val_str_output(""), r#""""#);
    }

    #[test]
    fn test_val_str_control_chars() {
        assert_eq!(val_str_output("\n"), r#""\n""#);
        assert_eq!(val_str_output("\r"), r#""\r""#);
        assert_eq!(val_str_output("\t"), r#""\t""#);
        assert_eq!(val_str_output("\x08"), r#""\b""#);
        assert_eq!(val_str_output("\x0C"), r#""\f""#);
        // U+0001 → \u0001
        assert_eq!(val_str_output("\x01"), r#""\u0001""#);
        assert_eq!(val_str_output("\x1F"), r#""\u001f""#);
    }

    #[test]
    fn test_val_str_unicode_passthrough() {
        // Non-ASCII but above U+001F should pass through unescaped
        assert_eq!(val_str_output("café"), "\"café\"");
        assert_eq!(val_str_output("日本語"), "\"日本語\"");
    }

    #[test]
    fn test_f64_edge_cases() {
        let mut jw = JsonWriter::new();
        jw.val_f64(f64::NAN);
        assert_eq!(jw.into_string(), "null");

        let mut jw = JsonWriter::new();
        jw.val_f64(f64::INFINITY);
        assert_eq!(jw.into_string(), "null");

        let mut jw = JsonWriter::new();
        jw.val_f64(f64::NEG_INFINITY);
        assert_eq!(jw.into_string(), "null");

        let mut jw = JsonWriter::new();
        jw.val_f64(-0.0_f64);
        let s = jw.into_string();
        // -0.0 should be written as a number (not null)
        assert!(
            s == "-0" || s == "0" || s == "-0.0" || s == "0.0",
            "got: {s}"
        );

        let mut jw = JsonWriter::new();
        jw.val_f64(2.78);
        let s = jw.into_string();
        assert!(s.contains("2.78"), "got: {s}");
    }

    #[test]
    fn test_timestamp_format() {
        // Test known SystemTime value: Unix epoch
        let epoch = SystemTime::UNIX_EPOCH;
        let s = format_timestamp(epoch);
        assert_eq!(s, "1970-01-01T00:00:00.000000Z");

        // Test another known value: 2026-02-20T12:00:00Z = 1771588800 seconds
        let t = SystemTime::UNIX_EPOCH + std::time::Duration::from_secs(1771588800);
        let s = format_timestamp(t);
        assert_eq!(s, "2026-02-20T12:00:00.000000Z");
    }

    #[test]
    fn test_timestamp_microsecond_precision() {
        // 2026-02-20T12:00:00Z + 123456 µs → .123456
        let t = SystemTime::UNIX_EPOCH
            + std::time::Duration::from_micros(1_771_588_800 * 1_000_000 + 123_456);
        let s = format_timestamp(t);
        assert_eq!(s, "2026-02-20T12:00:00.123456Z");

        // Exactly 1 µs past epoch
        let t = SystemTime::UNIX_EPOCH + std::time::Duration::from_micros(1);
        let s = format_timestamp(t);
        assert_eq!(s, "1970-01-01T00:00:00.000001Z");

        // 999999 µs (all six digits occupied)
        let t = SystemTime::UNIX_EPOCH + std::time::Duration::from_micros(999_999);
        let s = format_timestamp(t);
        assert_eq!(s, "1970-01-01T00:00:00.999999Z");
    }
}