slog: API backwards compatibility investigation

[karalabe]

We need to figure out exactly what the fallout would be from switching to slog from our internal log package and how we can create some adapters to keep the old functionality in dependent code. Ideally, we should have a way for users to use both the old and new APIs/packages until a deprecation period arrives, while we internally would switch over to the new slog version immediately.

[jwasinger]

copying this relevant comment from @holiman on the slog PR:

---

We should consider some options to make life simper for projects using go-ethereum/log as a library. Some options that I can think of are:

1. Put our slog stuff into go-ethereum/slog, and never touch log (add deprecation notices though). Easy for downstreams (they probably won't even notice).
2. Put our slogs stuff into either go-ethereum/slog or go-ethereum/log, but move the old stuff into go-ethereum/legacylog. Dependent projects will break, but we can just tell them to repoint the dependency from log to legacylog. There's even some go alias magic we can make use of.
3. Put our slogs stuff into either go-ethereum/slog or go-ethereum/log, but put our old stuff into a (dead) new repo: e.g. ethereum/geth-legacy/log. Dependent projects will break, but we can just tell them to repoint the dependency to the new repository. (Possibly use alias magic?)

I don't think it's good to do what we do right now, which just overwrites the log package in a non-backwards compatible way with no easy way to un-break. I mean, we don't want people to not be able to upgrade their geth-dependency.

---

Now that I think about it, none of these really preserve backwards-compatibility. Even option 1) breaks backwards compatibility as setting the root logger in the log would not apply to any logs made from Geth code.

Writing an adapter seems like it is something that would be somewhat complex but feasible. I'd have to think more about how it would be done though.

[holiman]

Now that I think about it, none of these really preserve backwards-compatibility.

Well, from an api-perspective, it does. Yes, the go-ethereum won't log to whatever you set from the outside, but that's a different (acceptable) type of breakage IMO.

[fjl]

I think what we should do is, move our slog customizations to a new package internal/slog, and create an adapter that relays log messages sent with the old logger through slog. That way, if there are any software projects using the geth logger, their messages will just be forwarded to slog. Performance of the adapter doesn't matter since we won't use it. We will also mark the log package deprecated and delete it later.

[karalabe]

I really don't want to move anything into internal. It was a bad idea, we ended up using it as a junk yard. My 2c, nuke everything inside and clean up the code.

[karalabe]

Ah wait, I actually agree with @fjl :)) I thought about something else.

[karalabe]

We've had an hour log discussion today about the compatibility issues and solutions, and we're kind of in agreement with the following approach and fallout:

The approach would be to gut out the log package and replace it's implementation with slog.

The fallout:

• People running Geth as a self contained command should not see any change. The new package internals have tests that verify that the output format is the same with the old and new code. This is IMO the most important thing as an update could silently break things.
• People running bits of go-ethereum as a library directly and being interested in the logs emitted (e.g. txpool logs) would hit a compilation error when upgrading to the new version of go-ethereum. For these people the change needed would be to replace the log initialization (so 1 line) to get their code fixed. Annoying, yes, but the issue would hit during dependency update time and not runtime, so you already have a dev actively doing it.
  • The alternative possibility of keeping the API stable (e.g. deprecating log and having a new slog for us to save that 1 liner initialization) would mean that the new go-ethereum library would integrate without any issues, but the logs would silently disappear as we're be pushing them into an uninitialized slog and not log15 any more which the user inited in their code. IMO this is worse, because instead of a build-time breakage, we have a silent runtime breakage.
• People running go-ethereum as a second order dependency (final app -> direct dependency -> indirect go-ethereum dep) would potentially hit a different issue. When they update their direct dependency, go modules will blindly pull in a new version of go-ethereum as the slog version will be compatible on a semantic versioning level to the log15 version. This will result in a build error on the second order dependencies.
  • This is unfortunate, but it still means a build error instead of a runtime error. Fixing the issue is slightly more annoying here, as it would require the indirect dependency to pin the go-ethereum version used by the direct dependency, until the direct dependency updates their code. This breakage would however only happen if the direct dep actually cares about the logs and does log handler inits. If it doesn't, then there's no breakage. We feel the probability is low enough that someone uses go-ethereum in a deep dependency stack, and does not care about go-ethereum enough to pin it, but does care about the go-ethereum logs.
• People using go-ethereum/log as a dependency will hit a build error upon upgrading, but it should be fixable with a single line initializer change. I don't think there would be many users outside of ourselves as it's a bit strange to rely on Geth's 500MB repo for a clone of log15.

[karalabe]

Closing per the suggestion above.