Stabilize and document __log.

[dpc]

Sometimes needs arise where one wants to deliver a custom logging statement to log crate. __log is exactly that function, but then anyone using it is risking breaking changes.

It seems to me once log API is considered stable, __log should be documented and stabilized as well.

[sfackler]

__log and its associated struct LogLocation are explicitly designed to be unstable and undocumented forever, since we are otherwise forever prevented from e.g. taking advantage of a future function!() macro to extend the location metadata.

[dpc]

The content of LogLocation can be extended without breaking anything, no?

[sfackler]

I'm a bit confused - why do you need to use __log if you're not assembling your own LogLocation?

[dpc]

RIght. Hmm... LogLocation could be assembled eg. by a macro, that in the future would be changed to fill the missing field with a defaults ... But I guess that's too much complication for no good reason.

Will there be any other addition? I mean - one could just add function : &'static str field right away and for now fill it with "".

[sfackler]

Who knows? function was just something I pulled from the top of my head.

[dpc]

Can't then log just bump version to 2.0 or something? :)

[sfackler]

Bumping the major version of log is pretty traumatic ecosystem-wise. Until everyone upgrades you'll be losing log messages from anything that still talks to the old version. It is not a thing I want to do every time we want to add some new metadata to log events.

[sfackler]

FYI, the only reason __log is public at all is that macros aren't hygenic with respect to privacy. It is the definition of an implementation detail.

[dpc]

I have a need to log things with custom meta information using LogLocation: https://github.com/dpc/slog-rs/blob/8ef65309610125e1ba024ae1d4f2eb4e2a0b58cb/crates/stdlog/lib.rs#L220

And it seems to me it's reasonable requirement, as "faking" line/file/module might be useful in some cases, when people don't want real information for whatever reason.

What if __log and LogLocation were stabilized, and any time anything change there, __logv2 and LogLocationv2 are created, while keeping __log and LogLocation as #[deprecated] backward compatibility forwarding things to __logv2? Macros itself will just use v2 versions.

[alexcrichton]

The functionality here seems pretty reasonable to me, integrating one log system into another. Stabilizing exactly __log, however, will likely never happen. (or at least I would prefer such)

I wonder if we could perhaps explore a more first class API here? Something like:

struct LogBuilder {
    // opaque
}

impl LogBuilder {
    fn new() -> LogBuilder { ... }

    fn line(&mut self, line: u32) -> &mut LogBuilder { ... }
    fn module(&mut self, module: &str) -> &mut LogBuilder { ... }
    // other builder methods ...

    fn emit(&mut self) { ... }
}

This way slog and other libraries could programmatically build log structures and the log crate also has the ability to add more fields over time if need be. The _log method would also stay as-is today, the implementation would likely just change.

Thoughts?

[sfackler]

We'd need to change that API a bit since line, module, etc are already required, unless we'd have emit panic which seems unfortunate.

[alexcrichton]

Perhaps yeah, although we could also just add arguments to new

[dpc]

Anything wrong with versioned __log and LogLocation?

[alexcrichton]

I personally much prefer extensible APIs to "versioned APIs". That way everyone always has the same ergonomic experience and it's not a huge diff to use new features.

[dpc]

Yes, normally me to. But in that case the API is kind of a backdoor anyway, and except few people noone can see it anyway.

My concerns are:

• builder boilerplate could not always get completely optimized away or will get in a way of some optimizations
• could there be any non-trivial changes to the logging record structure there would lead to troubes for the Builder having to support both new and old format?

If the above are not an issue, then Builder is clearly nicer.

[alexcrichton]

Oh I wasn't worried about perf here because I figured that once you hit this point you've concluded "yes a log should happen" and whatever happens there will completely dwarf some code to assemble the message.

It's true yeah though that if a builder were stabilized we'd have to be very confident that it would be sufficient for an incredibly long time. I'm pretty confident in this, though, as the builders in the standard library have worked out very well so far.

[sfackler]

Fixed by #211.