slog-rs/json

Json formatter for slog-rs

Getting started Introduction FAQ
Crate list

slog-rs - The Logging for Rust

You might consider using tracing instead

It's been a while since slog was created and it served Rust community well all this time. It remains a stable, featureful and battle-tested library, used in many important projects.

In last few years, another ecosystem for Rust was created with similar features and a very good support for debugging async code and already larger dev team and community.

Please check tracing and see if it is more suitable for your use-case. It seems that it is already a go-to logging/tracing solution for Rust.

Reasons you might want to stick with slog anyway:

• async support doesn't benefit you
• you consider mature, stable code & API a plus
• it has some features that tracing is missing
• great performance (I have NOT done any comparison, but slog's performance is very good).

Introduction (please read)

slog is an ecosystem of reusable components for structured, extensible, composable and contextual logging for Rust.

The ambition is to be The Logging Library for Rust. slog should accommodate a variety of logging features and requirements. If there is a feature that you need and standard log crate is missing, slog should have it.

This power comes with a little steeper learning curve, so if you experience any problems, please join slog-rs gitter channel to get up to speed. If you'd like to take a quick, convenient route, consider using sloggers wrapper library.

While the code is reliable, the documentation sometimes could use an improvement. Please report all issues and ideas.

Features & technical documentation

Most of the interesting documentation is auto-generated and hosted on https://docs.rs.

Go to docs.rs/slog to read about features and APIs (examples included).

Note: slog is just a core, and the actual functionality is inside many feature crates. To name a few:

• slog-term for terminal output
• slog-async for asynchronous logging
• slog-json for logging JSON
• slog-syslog for logging to syslog
• sloggers for convenience methods (note: 3rd-party library)

There are many more slog feature crates. Search for more slog features on crates.io. It is easy to write and publish new ones. Look through all the existing crates using slog for examples and ideas.

Terminal output example

slog-term is only one of many slog features - useful showcase, multi-platform, and featuring eg. automatic TTY detection and colors.

See following screenshot: same output in both compact and full output mode.

Using & help

Please use slog-rs gitter channel to ask for help or discuss slog features.

See examples/features.rs for full quick code example overview.

Read Documentation for details and features.

To report a bug or ask for features use github issues.

Slog community

Slog related crates are hosted under slog github organization.

Dawid Ciężarkiewicz is the original author and current maintainer of slog and therefore self-appointed benevolent dictator over the project. When working on slog Dawid follows and expects everyone to follow his Code of Conduct.

Any particular repositories under slog ecosystem might be created, controlled, maintained by other entities with various levels of autonomy. Lets work together toward a common goal in a respectful and welcoming atmosphere!

Verification Recommendation

To help with the maintained, the ownership of this crate is potentially shared between multiple developers. It is recommended to always use cargo-crev to verify the trustworthiness of each of your dependencies, including this one.

json's Issues

Release 2.5.0

Please can 2.5.0 be released to crates.io?

I'm keen to take #25 as it reduces friction when projects at my workplace use slog-json.

Make it easier to log inline JSON with the "nested-values" feature

It surprised me that I couldn't log, say, a Vec<i64> inline into slog-json easily, i.e., as a field

'nested-value': [0, 1, ...]

It turns out that this is possible, but it's not obvious how to do so, and there seem to be lots of conflicting information and questions about how to do this on the web (several threads in gitter, for example). I made https://github.com/ncalexan/slog-nested-values-example to work out what I needed to do to achieve this, so I'll just drop that link here for the next person trying to work this out. But I have two requests:

1. Can we expose the obvious SerdeValueWrapper<T> (with a JSON string as fallback?) as part of this crate? (Or slog-rs itself, I guess.) There's not much sense having everybody discover the incantations themselves. I imagine that the loss of flexibility is real, but can we support both paths?
2. Can we add examples and tests of this functionality, 'cuz it's not obvious that it exists without that? There's not much sense not capturing this useful functionality.

Thoughts?

Viewer program

I could see this becoming the de-facto standard logging format for Slog, if a viewer program were to be provided alongside it. Perhaps one that simply reads from the JSON format, and outputs in the slog-term format, with some basic searching and date-time range capabilities. Is this in your plans?

Discussion: make `Json` more flexible WRT sharing across threads

Json currently fails to satisfy slog's SendSyncUnwindSafeDrain because of the internal RefCell, necessitating wrapping it in a Mutex to use it as a drain in slog::Logger. This seems redundant, especially when using Json with io::Stdout or io::Stderr which also use mutexes internally and can be shared across threads.

The simplest solution might be to just replace RefCell with Mutex. Uncontended single-thread access of a mutex isn't much more expensive than RefCell, and since slog::Logger requires Send + Sync + UnwindSafe anyway, it seems more than reasonable just to use Mutex. Of course, there is the issue of poisoning; to be backwards-compatible we could either just ignore poisoning or wrap the poison error in io::Error.

However, I would prefer a more general solution that also allows us to avoid using Mutex for internally synchronized writers like Stdout/Stderr. I'm thinking it would look something like this:

pub struct RecordSerializer<'a> { /**/ }

impl<'a> RecordSerializer<'a> {
    /// Write out the log record contained in this serializer to `write`.
    pub fn write_to<W: Write>(self, write: W) -> io::Result<()> { /**/ }
}

pub trait SharedWrite {
    /// An error type that can wrap `io::Error` along with any locking error this impl may produce.
    type Error: From<io::Error>;

    /// Provide `serializer` with a `std::io::Write` impl via its `write_to()` method
    fn with_writer(&self, serializer: RecordSerializer) -> Result<(), Self::Error>;

    // I initially conceived of a `lock()` method that returned an impl of `io::Write` but it
    // would have required generic associated types to bind the lifetime to the `&self` param
}

pub enum MutexWriteError {
    Io(io::Error),
    Poisoned,
}

impl<T> From<PoisonError<T>> for MutexWriteError { /* */ }
impl From<io::Error> for MutexWriteError { /* */ }

impl<W: Write> SharedWrite for Mutex<W> {
    type Error = MutexWriteError;

    fn with_writer(&self, serializer: RecordSerializer) -> Result<(), Self::Error> {
        let writer = self.lock()?;
        serializer.write_to(writer).map_err(Into::into)
    }
}

impl SharedWrite for Stdout {
    type Error = io::Error;
 
    fn with_writer(&self, serializer: RecordSerializer) -> Result<(), Self::Error> {
        serializer.write_to(self.lock())
    }   
}

impl SharedWrite for Stderr {
    type Error = io::Error;
 
    fn with_writer(&self, serializer: RecordSerializer) -> Result<(), Self::Error> {
        serializer.write_to(self.lock())
    }   
}

The main issue is that this would be a breaking change to Json's API if we changed it to take SharedWrite instead of Write; to be backwards-compatible this would have to be introduced along with a new type that pretty much just duplicates Json's API, which isn't great either.

Relicense under MPL/Apache/MIT

Following up on:

• slog-rs/slog#182
• slog-rs/slog#134

Would it be possible to relicense slog-json under the same MPL-2.0 OR Apache-2.0 OR MIT triple licensing scheme used elsewhere for the slog ecosystem crates?

Enhancement: Pretty-printed JSON output

It would be nice for development if I could conditionally enable pretty-printed JSON output.

How to write to a TcpStream without lots of `write()`s?

I'm currently using the Json drain to write to a TCP port like this:

    let writer = TcpStream::connect("localhost:5000").unwrap();
    let drain = slog_json::Json::default(writer);
    let logger = slog::Logger::root(Mutex::new(drain).map(slog::Fuse), o!());

The problem with this approach is that the JSON serializer will call write() on the TCP connection for every token ({, ", msg, ", : etc.). I believe this results in quite a performance hit.

I'm thinking to use a BufWriter around the TcpStream to allow buffering of the individual writes. To ensure that every log message is sent through the wire I'd want to call flush() after each message though.
Do you think that's a good solution?
I will open a pull request to add the flush() call if you agree.