log: Add TimestampFormat and Timeformat.#514
Conversation
ChrisHines
force-pushed
the
defer-time-format
branch
from
184db25 to
0dc4eff
Compare
|
One of the best traits of go-kit in general, and log package, is the minimal interface. If |
| // TimestampFormat returns a Valuer that produces a TimeFormat value from | ||
| // layout and the time returned by t. Users will probably want to use | ||
| // DefaultTimestamp or DefaultTimestampUTC. | ||
| func TimestampFormat(t func() time.Time, layout string) Valuer { |
There was a problem hiding this comment.
- An alternate name to consider instead of
t:now.
There was a problem hiding this comment.
Using now makes sense to me, but I think t can also be fine, if it's explained a bit more didactically; I think I want the comment here to explain the "why" rather than the "what", e.g.
// TimestampFormat can be used to create custom time formats for log timestamps.
// The t function will be invoked to get the time to format; unless you're doing
// something tricky, pass time.Now. The layout string is passed to Time.Format.
//
// Most users will want to use DefaultTimestamp or DefaultTimestampUTC, which
// are TimestampFormats that use the RFC3339Nano format.There was a problem hiding this comment.
I'm going to stick with the name t because the returned time doesn't have to represent the current time. I agree that the comment will need to be reworded when TimeFormat is not exported. Thanks for the wordsmithing.
| } | ||
|
|
||
| // A TimeFormat represents an instant in time and a layout used when | ||
| // marshaling to a text format. |
There was a problem hiding this comment.
- If this does stay an exported type, consider mentioning that the layout must be one accepted by
time.Time.Format.
peterbourgon
left a comment
peterbourgon
left a comment
There was a problem hiding this comment.
A couple of minor things I'd like to see addressed, but overall LGTM!
| // TimestampFormat returns a Valuer that produces a TimeFormat value from | ||
| // layout and the time returned by t. Users will probably want to use | ||
| // DefaultTimestamp or DefaultTimestampUTC. | ||
| func TimestampFormat(t func() time.Time, layout string) Valuer { |
There was a problem hiding this comment.
Using now makes sense to me, but I think t can also be fine, if it's explained a bit more didactically; I think I want the comment here to explain the "why" rather than the "what", e.g.
// TimestampFormat can be used to create custom time formats for log timestamps.
// The t function will be invoked to get the time to format; unless you're doing
// something tricky, pass time.Now. The layout string is passed to Time.Format.
//
// Most users will want to use DefaultTimestamp or DefaultTimestampUTC, which
// are TimestampFormats that use the RFC3339Nano format.| type TimeFormat struct { | ||
| Time time.Time | ||
| Layout string | ||
| } |
There was a problem hiding this comment.
As others have said, I think this can be safely unexported?
log/value.go
Outdated
|
|
||
| // MarshalText implements encoding.TextMarshaller. | ||
| func (tf TimeFormat) MarshalText() (text []byte, err error) { | ||
| b := make([]byte, 0, len(tf.Layout)+10) |
There was a problem hiding this comment.
Can you constize this literal 10 so we get a name with some semantic meaning?
There was a problem hiding this comment.
I can add a brief comment, but I don't know what to name the constant? Do you have any suggestions?
For reference, the technique is a reduction of the standard library code for time.Time.Format, seen here: https://golang.org/src/time/format.go?s=14285:14327#L437. Unfortunately that code doesn't provide any naming help or even document why they picked 10.
There was a problem hiding this comment.
Oh! Well, if the magic number is OK there, I reckon it's OK here too. Nevermind my request.
|
Thanks for the input everyone. I'll make updates based on your feedback this evening. |
- TimestampFormat is a function to produce time Valuers with arbitrary time formats. - The Valuer generates values of the unexported type timeFormat, a value that defers formating timestamps until serialization, which improves performance when a log event is not serialized. - DefaultTimestamp and DefaultTimestampUTC are now created using TimestampFormat.
ChrisHines
force-pushed
the
defer-time-format
branch
from
0dc4eff to
584a942
Compare
4 participants
serialization, which improves performance when a log event is not
serialized.
with arbitrary time formats.
TimestampFormat.
Benchmarks from log/level showing the benefits: