Make the Handler and Format interfaces more orthogonal. about log15 HOT 3 OPEN

Interesting proposal. If we adopted this, it would mean the following:

• Most (maybe all) Handler chains would need to end with a new Handler that inserted the special keys (level, time, message) into the context
• Format is still not composable, so it's still not easy to customize them without copying
  Format code from the individual implementations

It seems like regardless of whether we adopt this or not, we should extract out all the code which is shared between Formats into Handlers. (Putting the special keys into the context, normalizing values into strings via the TextMarshaller interface, etc). The downside to this is that I suspect it will greatly increase the surface area of log15's API. This means both more APIs to support and it makes it more difficult to use because of the additional choices a developer will see. We could consider putting it into a format sub-package, I suppose.

from log15.

@inconshreveable: Your comments above are thought provoking. I have several things to say in response, but I am going to break them into two posts. This post is a direct response to your comments. The second post will be a more abstract rethinking of the proposal.

RE: Handler Chains

As it stands now most Handler chains end with one of the Handlers that accepts a Format argument which are FileHandler, NetHandler, or StreamHandler. FileHandler and NetHandler are thin wrappers around StreamHandler which contains the only call to Format.Format within log15.

If we provide a Handler that populates the context with the special keys, then, as a convenience, StreamHandler could add it to the chain just as it currently does for LazyHandler and SyncHandler. However, it may be cleaner to simply put the special keys directly into the context.

RE: Composable Formats

I don't consider it a goal to make Format composable. I am not sure what that buys us. Since Formats convert structured data into unstructured []bytes it seems rather difficult to create chains of them.

As mentioned in the proposal's rationale, Formats would support customization by supporting the encoding.TextMarshaller interface.

from log15.

@inconshreveable: While considering your comments it struck me that the Format interface is really better thought of as an Encoder along the lines of json.Encoder, gob.Encoder, and xml.Encoder. This name convey the idea that the output should be machine readable and that individual values may implement the encoding.*Marshaller interfaces to customize their layout. A typical logging pipeline would look as follows.

1. Logger
2. Handler
3. Handler
4. ....
5. Handler
6. Encoder -> *Marshallers
7. io.Writer

We would declare Encoder as:

// An Encoder encodes log contexts.
type Encoder interface {
    // Encode encodes the alternating pairs of string keys and values in ctx.
    // Implementations should check for values that implement the interfaces
    // of the standard library's encoding package.
    Encode(ctx []interface{}) error
}

In this design the responsibilities are cleanly divided:

• Handler chains produce log contexts ([]interface{} with alternating key/value pairs).
• Encoders control the record format for a log context and provide default value formats.
• Values optionally control their format by implementing encoding.*Marshaller.

We give Encoders more implementation flexibility by not requiring them to return a []byte. Also, a JsonEncoder or XmlEncoder can simply pass values on to a json.Encoder or xml.Encoder and take advantage of those packages's awareness of the encoding.TextMarshaller interface.

from log15.