Tracking issue for kv_unstable (structured logging)

[KodrAus]

Tracking issue for the implementation of #296. See also #149

• Initial implementation (Build out initial key values API #324)
• Integration with frameworks and loggers:
  • slog
    • Zero-allocation conversion between slog::Value and log::kv::Value. We should be able to do zero-allocation conversion from log to slog, but may need to allocate from slog to log.
  • tracing (log: Support structured values tokio-rs/tracing#341)
    • Zero-allocation conversion between tracing::Value and log::kv::Value in the event! macro (Make it easier to create a Value from owned or erased external types #339)
    • Capture std::error::Errors as Values
  • fern
  • async-log
  • std-logger (Print key values Thomasdezeeuw/std-logger#14)
    • Some way to tell whether a Source has any key-value pairs (Add a count method to Source #329)
  • femme
  • env_logger (Add support for Key-Value data in log records. rust-cli/env_logger#137)
  • antlog (an experimental wrapper to prove out requirements)
    • A way to get specific values (Add a Source::get method for finding a single value #335)
    • A way to coerce a value to a common type (Support coercing structured Values into primitive types #379)
  • Please suggest others to track!
• Explore macro support (key_value capable log macros #343)
  • log!("msg {}", interpolated, { key: value }) (kv macro support #353) - We ended up having to revert this in log, but are experimenting externally
  • log_kv_macro
  • log_macros
• Integration with serialization frameworks:
  • serde
    • Conversion between serde::Serialize and std::fmt::Debug (Add key and value methods to DebugMap rfcs#2696). See serde_fmt.
  • sval (Add structured support to kv::Value using sval #342)
• Micro benchmarks
• Documentation and examples
• Stabilization review
• Open questions
  • Should Source::count return a Result<usize> instead of a plain usize?

[yoshuawuyts]

@KodrAus thanks for all the work you've put into this (and linking to this issue from a forum post).

I was curious: is there a release planned that includes the beta version of kv? I actually wanted to use the beta for async-log, but given there wasn't any release yet it wasn't possible 😅

[KodrAus]

Hi @yoshuawuyts! 👋

Right now any release of log we publish will include this API under the kv_unstable feature gate, but we're not ready to commit to backwards compatibility just yet. So if you depend on log from git then you can access the API:

[dependencies.log]
git = "https://github.com/rust-lang-nursery/log.git"
features = ["kv_unstable"]

I think what we need are a few draft PRs in some of these log frameworks that tease out any breaking changes we should make, and then will be able to publish a release that replaces the kv_unstable feature gate with a kv one.

[yoshuawuyts]

Right now any release of log we publish will include this API under the kv_unstable feature gate,

Oh oops, maybe I was being a bit vague. The last release on crates.io was done in October 2018, which means currently no releases ship with kv_unstable on crates.io. Which in turn (I believe) means we can't ship any versions to crates.io.

In order to help test this feature, it would be nice if there was a release on crates.io with the ["kv_unstable"] feature available. For experimental technology such as async-log I think we can get away with publishing a version that directly depends on this feature, and keep updating it as it's polished.

So my question is: could a version be of log be published to crates.io that includes the experimental flag?

P.S. Thanks for taking time out of your day to reply to my questions!

[KodrAus]

In order to help test this feature, it would be nice if there was a release on crates.io with the ["kv_unstable"] feature available. For experimental technology such as async-log I think we can get away with publishing a version that directly depends on this feature, and keep updating it as it's polished.

Ah this sounds fair enough. I think we can get pretty far without needing to break anything, but it's probably going to happen at some point. But right now it is harder for folks to get started with these new APIs, so once #339 lands I'll put together a release so you can depend on it from crates.io and browse the docs on docs.rs.

[yoshuawuyts]

@KodrAus in the top-level post there's an entry about "Explore macro support". Do you have any plans to experiment with this?

We've integrated key-value logging in lrlna/femme#1; all that's missing now is a way to create key-value pairs and send them to a logger. Even a small code example would be helpful, but ideally there'd be a small log crate that could work with this.

Also: is it perhaps useful to open a separate issue to track/discuss logging macros?

---

edit 2019-07-21:
Ah, I think I figured out how to log a kv-pair!

let record = log::Record::builder().key_values(kv_pairs).build();
log::logger().log(&record);

[KodrAus]

Ah yes that Record::key_values method is the way you can attach key-value pairs to a record in the absence of macro support. It needs to be a &dyn Source.

Opening a separate issue to design macro support sounds like a good idea! We’ve got a couple of constraints but also plenty of opportunity to improve things.

[yoshuawuyts]

Macro issue created: #343