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 |
//! | [`JsonLayer::with_buffer_capacity_limit`] | `4096` | Capacity threshold for per-thread buffer shrinking |
//!
//! # 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::cell::Cell;
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 {
        write_timestamp(SystemTime::now(), w)
    }
}

// Extension type stored in span data
struct SpanFields(Vec<u8>);

thread_local! {
    static EVENT_BUF: Cell<Vec<u8>> = const { Cell::new(Vec::new()) };
}

/// 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,
    buf_cap_limit: usize,
}

impl<W, T> JsonLayer<W, T> {
    const DEFAULT_BUF_CAPACITY: usize = 256;
    const DEFAULT_BUF_CAP_LIMIT: usize = 4096;
}

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,
            buf_cap_limit: Self::DEFAULT_BUF_CAP_LIMIT,
        }
    }
}

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
    }

    /// Set the capacity threshold at which the per-thread formatting buffer
    /// is shrunk back to its default size after each event.
    ///
    /// The formatting buffer is reused across events on the same thread to
    /// avoid allocations. If an unusually large event grows the buffer beyond
    /// this limit, it is shrunk back to 256 bytes after that event to reclaim
    /// memory.
    ///
    /// Default: **4096** bytes.
    pub fn with_buffer_capacity_limit(mut self, limit: usize) -> Self {
        self.buf_cap_limit = limit;
        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,
            buf_cap_limit: self.buf_cap_limit,
        }
    }

    /// 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_vec()));
    }

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

    fn on_event(&self, event: &Event<'_>, ctx: Context<'_, S>) {
        EVENT_BUF.with(|cell| {
            let mut buf = cell.take();
            buf.clear();
            let mut jw = JsonWriter::from_vec(buf);

            jw.obj_start();

            // Timestamp (absent when timer is `()` / `without_time()`).
            // Written directly into the JsonWriter via fmt::Write to avoid a
            // temporary String allocation. The value is NOT JSON-escaped;
            // FormatTime implementations are expected to produce only
            // printable ASCII (digits, dashes, colons, etc.).
            let wrote_timestamp = {
                let rollback = jw.len();
                jw.raw(b"\"timestamp\":\"");
                let val_start = jw.len();
                {
                    let mut fw = FmtWriter::new(&mut jw);
                    let _ = self.timer.format_time(&mut fw);
                }
                if jw.len() > val_start {
                    jw.push_byte(b'"');
                    true
                } else {
                    jw.truncate(rollback);
                    false
                }
            };

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

            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_debug(&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 mut writer = self.make_writer.make_writer();
            let _ = writer.write_all(jw.as_bytes());

            // Return buffer for reuse, shrinking if an outlier event grew it
            let mut buf = jw.into_vec();
            if buf.capacity() > self.buf_cap_limit {
                buf.shrink_to(Self::DEFAULT_BUF_CAPACITY);
            }
            cell.set(buf);
        });
    }
}

/// Write a `SystemTime` as RFC 3339 with microsecond precision in UTC directly
/// into any `fmt::Write` sink, avoiding an intermediate `String` allocation.
fn write_timestamp(t: SystemTime, w: &mut impl std::fmt::Write) -> std::fmt::Result {
    let dur = t.duration_since(SystemTime::UNIX_EPOCH).unwrap_or_default();
    let secs = dur.as_secs();
    let micros = dur.subsec_micros();

    let (year, month, day, hour, min, sec) = secs_to_datetime(secs);

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

/// Format a `SystemTime` as RFC 3339 with microsecond precision in UTC.
/// e.g. "2026-02-20T12:00:00.000000Z"
#[cfg(test)]
fn format_timestamp(t: SystemTime) -> String {
    let mut buf = String::with_capacity(27);
    write_timestamp(t, &mut buf).unwrap();
    buf
}

/// 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::*;

    /// Convert a JsonWriter to a String for test assertions.
    fn to_string(jw: JsonWriter) -> String {
        String::from_utf8(jw.into_vec()).unwrap()
    }

    /// 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);
        to_string(jw)
    }

    #[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!(to_string(jw), "null");

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

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

        let mut jw = JsonWriter::new();
        jw.val_f64(-0.0_f64);
        let s = to_string(jw);
        // -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 = to_string(jw);
        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");
    }
}