|
11 | 11 | // importers can entirely replace flume if they wish. Alternately, importers can use flume to configure |
12 | 12 | // the library's log output, and/or redirect it into the overall program's log stream. |
13 | 13 | // |
14 | | -// Logging |
| 14 | +// # Logging |
15 | 15 | // |
16 | 16 | // This package does not offer package level log functions, so you need to create a logger instance first: |
17 | 17 | // A common pattern is to create a single, package-wide logger, named after the package: |
18 | 18 | // |
19 | | -// var log = flume.New("mypkg") |
| 19 | +// var log = flume.New("mypkg") |
20 | 20 | // |
21 | 21 | // Then, write some logs: |
22 | 22 | // |
23 | | -// log.Debug("created user", "username", "frank", "role", "admin") |
| 23 | +// log.Debug("created user", "username", "frank", "role", "admin") |
24 | 24 | // |
25 | 25 | // Logs have a message, then matched pairs of key/value properties. Child loggers can be created |
26 | 26 | // and pre-seeded with a set of properties: |
27 | 27 | // |
28 | | -// reqLogger := log.With("remoteAddr", req.RemoteAddr) |
| 28 | +// reqLogger := log.With("remoteAddr", req.RemoteAddr) |
29 | 29 | // |
30 | 30 | // Expensive log events can be avoid by explicitly checking level: |
31 | 31 | // |
32 | | -// if log.IsDebug() { |
33 | | -// log.Debug("created resource", "resource", resource.ExpensiveToString()) |
34 | | -// } |
| 32 | +// if log.IsDebug() { |
| 33 | +// log.Debug("created resource", "resource", resource.ExpensiveToString()) |
| 34 | +// } |
35 | 35 | // |
36 | 36 | // Loggers can be bound to context.Context, which is convenient for carrying |
37 | 37 | // per-transaction loggers (pre-seeded with transaction specific context) through layers of request |
38 | 38 | // processing code: |
39 | 39 | // |
40 | | -// ctx = flume.WithLogger(ctx, log.With("transactionID", tid)) |
41 | | -// // ...later... |
42 | | -// flume.FromContext(ctx).Info("Request handled.") |
| 40 | +// ctx = flume.WithLogger(ctx, log.With("transactionID", tid)) |
| 41 | +// // ...later... |
| 42 | +// flume.FromContext(ctx).Info("Request handled.") |
43 | 43 | // |
44 | 44 | // The standard Logger interface only supports 3 levels of log, DBG, INF, and ERR. This is inspired by |
45 | 45 | // this article: https://dave.cheney.net/2015/11/05/lets-talk-about-logging. However, you can create |
46 | 46 | // instances of DeprecatedLogger instead, which support more levels. |
47 | 47 | // |
48 | | -// Configuration |
| 48 | +// # Configuration |
49 | 49 | // |
50 | 50 | // There are several package level functions which reconfigure logging output. They control which |
51 | 51 | // levels are discarded, which fields are included in each log entry, and how those fields are rendered, |
52 | 52 | // and how the overall log entry is rendered (JSON, LTSV, colorized, etc). |
53 | 53 | // |
54 | 54 | // To configure logging settings from environment variables, call the configuration function from main(): |
55 | 55 | // |
56 | | -// flume.ConfigFromEnv() |
| 56 | +// flume.ConfigFromEnv() |
57 | 57 | // |
58 | 58 | // This reads the log configuration from the environment variable "FLUME" (the default, which can be |
59 | 59 | // overridden). The value is JSON, e.g.: |
60 | 60 | // |
61 | | -// {"level":"INF","levels":"http=DBG","development"="true"} |
| 61 | +// {"level":"INF","levels":"http=DBG","development"="true"} |
62 | 62 | // |
63 | 63 | // The properties of the config string: |
64 | 64 | // |
65 | | -// - "level": ERR, INF, or DBG. The default level for all loggers. |
66 | | -// - "levels": A string configuring log levels for specific loggers, overriding the default level. |
67 | | -// See note below for syntax. |
68 | | -// - "development": true or false. In development mode, the defaults for the other |
69 | | -// settings change to be more suitable for developers at a terminal (colorized, multiline, human |
70 | | -// readable, etc). See note below for exact defaults. |
71 | | -// - "addCaller": true or false. Adds call site information to log entries (file and line). |
72 | | -// - "encoding": json, ltsv, term, or term-color. Configures how log entries are encoded in the output. |
73 | | -// "term" and "term-color" are multi-line, human-friendly |
74 | | -// formats, intended for terminal output. |
75 | | -// - "encoderConfig": a JSON object which configures advanced encoding settings, like how timestamps |
76 | | -// are formatted. See docs for go.uber.org/zap/zapcore/EncoderConfig |
77 | | -// |
78 | | -// - "messageKey": the label of the message property of the log entry. If empty, message is omitted. |
79 | | -// - "levelKey": the label of the level property of the log entry. If empty, level is omitted. |
80 | | -// - "timeKey": the label of the timestamp of the log entry. If empty, timestamp is omitted. |
81 | | -// - "nameKey": the label of the logger name in the log entry. If empty, logger name is omitted. |
82 | | -// - "callerKey": the label of the logger name in the log entry. If empty, logger name is omitted. |
83 | | -// - "lineEnding": the end of each log output line. |
84 | | -// - "levelEncoder": capital, capitalColor, color, lower, or abbr. Controls how the log entry level |
85 | | -// is rendered. "abbr" renders 3-letter abbreviations, like ERR and INF. |
86 | | -// - "timeEncoder": iso8601, millis, nanos, unix, or justtime. Controls how timestamps are rendered. |
87 | | -// "millis", "nanos", and "unix" are since UNIX epoch. "unix" is in floating point seconds. |
88 | | -// "justtime" omits the date, and just prints the time in the format "15:04:05.000". |
89 | | -// - "durationEncoder": string, nanos, or seconds. Controls how time.Duration values are rendered. |
90 | | -// - "callerEncoder": full or short. Controls how the call site is rendered. |
91 | | -// "full" includes the entire package path, "short" only includes the last folder of the package. |
| 65 | +// - "level": ERR, INF, or DBG. The default level for all loggers. |
| 66 | +// |
| 67 | +// - "levels": A string configuring log levels for specific loggers, overriding the default level. |
| 68 | +// See note below for syntax. |
| 69 | +// |
| 70 | +// - "development": true or false. In development mode, the defaults for the other |
| 71 | +// settings change to be more suitable for developers at a terminal (colorized, multiline, human |
| 72 | +// readable, etc). See note below for exact defaults. |
| 73 | +// |
| 74 | +// - "addCaller": true or false. Adds call site information to log entries (file and line). |
| 75 | +// |
| 76 | +// - "encoding": json, ltsv, term, or term-color. Configures how log entries are encoded in the output. |
| 77 | +// "term" and "term-color" are multi-line, human-friendly |
| 78 | +// formats, intended for terminal output. |
| 79 | +// |
| 80 | +// - "encoderConfig": a JSON object which configures advanced encoding settings, like how timestamps |
| 81 | +// are formatted. See docs for go.uber.org/zap/zapcore/EncoderConfig |
| 82 | +// |
| 83 | +// - "messageKey": the label of the message property of the log entry. If empty, message is omitted. |
| 84 | +// |
| 85 | +// - "levelKey": the label of the level property of the log entry. If empty, level is omitted. |
| 86 | +// |
| 87 | +// - "timeKey": the label of the timestamp of the log entry. If empty, timestamp is omitted. |
| 88 | +// |
| 89 | +// - "nameKey": the label of the logger name in the log entry. If empty, logger name is omitted. |
| 90 | +// |
| 91 | +// - "callerKey": the label of the logger name in the log entry. If empty, logger name is omitted. |
| 92 | +// |
| 93 | +// - "lineEnding": the end of each log output line. |
| 94 | +// |
| 95 | +// - "levelEncoder": capital, capitalColor, color, lower, or abbr. Controls how the log entry level |
| 96 | +// is rendered. "abbr" renders 3-letter abbreviations, like ERR and INF. |
| 97 | +// |
| 98 | +// - "timeEncoder": iso8601, millis, nanos, unix, or justtime. Controls how timestamps are rendered. |
| 99 | +// "millis", "nanos", and "unix" are since UNIX epoch. "unix" is in floating point seconds. |
| 100 | +// "justtime" omits the date, and just prints the time in the format "15:04:05.000". |
| 101 | +// |
| 102 | +// - "durationEncoder": string, nanos, or seconds. Controls how time.Duration values are rendered. |
| 103 | +// |
| 104 | +// - "callerEncoder": full or short. Controls how the call site is rendered. |
| 105 | +// "full" includes the entire package path, "short" only includes the last folder of the package. |
92 | 106 | // |
93 | 107 | // Defaults: |
94 | 108 | // |
95 | | -// { |
96 | | -// "level":"INF", |
97 | | -// "levels":"", |
98 | | -// "development":false, |
99 | | -// "addCaller":false, |
100 | | -// "encoding":"term-color", |
101 | | -// "encoderConfig":{ |
102 | | -// "messageKey":"msg", |
103 | | -// "levelKey":"level", |
104 | | -// "timeKey":"time", |
105 | | -// "nameKey":"name", |
106 | | -// "callerKey":"caller", |
107 | | -// "lineEnding":"\n", |
108 | | -// "levelEncoder":"abbr", |
109 | | -// "timeEncoder":"iso8601", |
110 | | -// "durationEncoder":"seconds", |
111 | | -// "callerEncoder":"short", |
112 | | -// } |
113 | | -// } |
| 109 | +// { |
| 110 | +// "level":"INF", |
| 111 | +// "levels":"", |
| 112 | +// "development":false, |
| 113 | +// "addCaller":false, |
| 114 | +// "encoding":"term-color", |
| 115 | +// "encoderConfig":{ |
| 116 | +// "messageKey":"msg", |
| 117 | +// "levelKey":"level", |
| 118 | +// "timeKey":"time", |
| 119 | +// "nameKey":"name", |
| 120 | +// "callerKey":"caller", |
| 121 | +// "lineEnding":"\n", |
| 122 | +// "levelEncoder":"abbr", |
| 123 | +// "timeEncoder":"iso8601", |
| 124 | +// "durationEncoder":"seconds", |
| 125 | +// "callerEncoder":"short", |
| 126 | +// } |
| 127 | +// } |
114 | 128 | // |
115 | 129 | // These defaults are only applied if one of the configuration functions is called, like ConfigFromEnv(), ConfigString(), |
116 | 130 | // Configure(), or LevelsString(). Initially, all loggers are configured to discard everything, following |
|
120 | 134 | // |
121 | 135 | // Development mode: if "development"=true, the defaults for the rest of the settings change, equivalent to: |
122 | 136 | // |
123 | | -// { |
124 | | -// "addCaller":true, |
125 | | -// "encoding":"term-color", |
126 | | -// "encodingConfig": { |
127 | | -// "timeEncoder":"justtime", |
128 | | -// "durationEncoder":"string", |
129 | | -// } |
130 | | -// } |
| 137 | +// { |
| 138 | +// "addCaller":true, |
| 139 | +// "encoding":"term-color", |
| 140 | +// "encodingConfig": { |
| 141 | +// "timeEncoder":"justtime", |
| 142 | +// "durationEncoder":"string", |
| 143 | +// } |
| 144 | +// } |
131 | 145 | // |
132 | 146 | // The "levels" value is a list of key=value pairs, configuring the level of individual named loggers. |
133 | 147 | // If the key is "*", it sets the default level. If "level" and "levels" both configure the default |
134 | 148 | // level, "levels" wins. |
135 | 149 | // Examples: |
136 | 150 | // |
137 | | -// * // set the default level to ALL, equivalent to {"level"="ALL"} |
| 151 | +// - // set the default level to ALL, equivalent to {"level"="ALL"} |
138 | 152 | // *=INF // same, but set default level to INF |
139 | 153 | // *,sql=WRN // set default to ALL, set "sql" logger to WRN |
140 | 154 | // *=INF,http=ALL // set default to INF, set "http" to ALL |
141 | 155 | // *=INF,http // same as above. If name has no level, level is set to ALL |
142 | 156 | // *=INF,-http // set default to INF, set "http" to OFF |
143 | 157 | // http=INF // leave default setting unchanged. |
144 | 158 | // |
145 | | -// Factories |
| 159 | +// # Factories |
146 | 160 | // |
147 | 161 | // Most usages of flume will use its package functions. The package functions delegate to an internal |
148 | 162 | // instance of Factory, which a the logger registry. You can create and manage your own instance of |
|
0 commit comments