[go: nahoru, domu]

Skip to content

Commit

Permalink
Make API for omitting keys more approachable. (#725)
Browse files Browse the repository at this point in the history
* Explicitly document key omission in encoding

Currently encoders will omit fields when encoding log entries if the key
configured for that field is set to the empty string. However, this
behavior isn't documented or specified explicitly as being part of the
interface for encoding.

This adds documentation to the `Encoder` interface that explicitly
outlines the behavior that should be implemented when omitting fields.

* Add key for omission to package API

The empty string can be used to omit a key from a log line. However,
there's no explicitly exposed API for using this behavior.

This cleans up the API for users by allowing them to use a constant for
omitting the key instead of throwing around `""` everywhere, or making
their own constant and hoping that `""` will always omit the key.
  • Loading branch information
juicemia authored and prashantv committed Jul 9, 2019
1 parent 853ac18 commit 9a9fa7d
Show file tree
Hide file tree
Showing 3 changed files with 13 additions and 8 deletions.
6 changes: 5 additions & 1 deletion zapcore/encoder.go
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ import (
// behavior.
const DefaultLineEnding = "\n"

// OmitKey defines the key to use when callers want to remove a key from log output.
const OmitKey = ""

// A LevelEncoder serializes a Level to a primitive type.
type LevelEncoder func(Level, PrimitiveArrayEncoder)

Expand Down Expand Up @@ -343,6 +346,7 @@ type Encoder interface {
Clone() Encoder

// EncodeEntry encodes an entry and fields, along with any accumulated
// context, into a byte buffer and returns it.
// context, into a byte buffer and returns it. Any fields that are empty,
// including fields on the `Entry` type, should be omitted.
EncodeEntry(Entry, []Field) (*buffer.Buffer, error)
}
12 changes: 6 additions & 6 deletions zapcore/encoder_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ func TestEncoderConfiguration(t *testing.T) {
{
desc: "skip level if LevelKey is omitted",
cfg: EncoderConfig{
LevelKey: "",
LevelKey: OmitKey,
TimeKey: "T",
MessageKey: "M",
NameKey: "N",
Expand All @@ -140,7 +140,7 @@ func TestEncoderConfiguration(t *testing.T) {
desc: "skip timestamp if TimeKey is omitted",
cfg: EncoderConfig{
LevelKey: "L",
TimeKey: "",
TimeKey: OmitKey,
MessageKey: "M",
NameKey: "N",
CallerKey: "C",
Expand All @@ -159,7 +159,7 @@ func TestEncoderConfiguration(t *testing.T) {
cfg: EncoderConfig{
LevelKey: "L",
TimeKey: "T",
MessageKey: "",
MessageKey: OmitKey,
NameKey: "N",
CallerKey: "C",
StacktraceKey: "S",
Expand All @@ -178,7 +178,7 @@ func TestEncoderConfiguration(t *testing.T) {
LevelKey: "L",
TimeKey: "T",
MessageKey: "M",
NameKey: "",
NameKey: OmitKey,
CallerKey: "C",
StacktraceKey: "S",
LineEnding: base.LineEnding,
Expand All @@ -197,7 +197,7 @@ func TestEncoderConfiguration(t *testing.T) {
TimeKey: "T",
MessageKey: "M",
NameKey: "N",
CallerKey: "",
CallerKey: OmitKey,
StacktraceKey: "S",
LineEnding: base.LineEnding,
EncodeTime: base.EncodeTime,
Expand All @@ -216,7 +216,7 @@ func TestEncoderConfiguration(t *testing.T) {
MessageKey: "M",
NameKey: "N",
CallerKey: "C",
StacktraceKey: "",
StacktraceKey: OmitKey,
LineEnding: base.LineEnding,
EncodeTime: base.EncodeTime,
EncodeDuration: base.EncodeDuration,
Expand Down
3 changes: 2 additions & 1 deletion zapcore/entry.go
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,8 @@ func (ec EntryCaller) TrimmedPath() string {

// An Entry represents a complete log message. The entry's structured context
// is already serialized, but the log level, time, message, and call site
// information are available for inspection and modification.
// information are available for inspection and modification. Any fields left
// empty will be omitted when encoding.
//
// Entries are pooled, so any functions that accept them MUST be careful not to
// retain references to them.
Expand Down

0 comments on commit 9a9fa7d

Please sign in to comment.