/
options.go
303 lines (258 loc) · 10.5 KB
/
options.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
// Copyright 2017 Istio Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package log
import (
"fmt"
"sort"
"strings"
"github.com/spf13/cobra"
"go.uber.org/zap/zapcore"
)
const (
DefaultScopeName = "default"
OverrideScopeName = "all"
defaultOutputLevel = InfoLevel
defaultStackTraceLevel = NoneLevel
defaultOutputPath = "stdout"
defaultErrorOutputPath = "stderr"
defaultRotationMaxAge = 30
defaultRotationMaxSize = 100 * 1024 * 1024
defaultRotationMaxBackups = 1000
)
// Level is an enumeration of all supported log levels.
type Level int
const (
// NoneLevel disables logging
NoneLevel Level = iota
// FatalLevel enables fatal level logging
FatalLevel
// ErrorLevel enables error level logging
ErrorLevel
// WarnLevel enables warn level logging
WarnLevel
// InfoLevel enables info level logging
InfoLevel
// DebugLevel enables debug level logging
DebugLevel
)
var levelToString = map[Level]string{
DebugLevel: "debug",
InfoLevel: "info",
WarnLevel: "warn",
ErrorLevel: "error",
FatalLevel: "fatal",
NoneLevel: "none",
}
var stringToLevel = map[string]Level{
"debug": DebugLevel,
"info": InfoLevel,
"warn": WarnLevel,
"error": ErrorLevel,
"fatal": FatalLevel,
"none": NoneLevel,
}
// Options defines the set of options supported by Istio's component logging package.
type Options struct {
// OutputPaths is a list of file system paths to write the log data to.
// The special values stdout and stderr can be used to output to the
// standard I/O streams. This defaults to stdout.
OutputPaths []string
// ErrorOutputPaths is a list of file system paths to write logger errors to.
// The special values stdout and stderr can be used to output to the
// standard I/O streams. This defaults to stderr.
ErrorOutputPaths []string
// RotateOutputPath is the path to a rotating log file. This file should
// be automatically rotated over time, based on the rotation parameters such
// as RotationMaxSize and RotationMaxAge. The default is to not rotate.
//
// This path is used as a foundational path. This is where log output is normally
// saved. When a rotation needs to take place because the file got too big or too
// old, then the file is renamed by appending a timestamp to the name. Such renamed
// files are called backups. Once a backup has been created,
// output resumes to this path.
RotateOutputPath string
// RotationMaxSize is the maximum size in megabytes of a log file before it gets
// rotated. It defaults to 100 megabytes.
RotationMaxSize int
// RotationMaxAge is the maximum number of days to retain old log files based on the
// timestamp encoded in their filename. Note that a day is defined as 24
// hours and may not exactly correspond to calendar days due to daylight
// savings, leap seconds, etc. The default is to remove log files
// older than 30 days.
RotationMaxAge int
// RotationMaxBackups is the maximum number of old log files to retain. The default
// is to retain at most 1000 logs.
RotationMaxBackups int
// JSONEncoding controls whether the log is formatted as JSON.
JSONEncoding bool
// logGRPC indicates that Grpc logs should be captured.
// This is enabled by a --log_output_level=grpc:<level> typically
logGRPC bool
outputLevels string
defaultOutputLevels string
logCallers string
stackTraceLevels string
useStackdriverFormat bool
extensions []Extension
}
// DefaultOptions returns a new set of options, initialized to the defaults
func DefaultOptions() *Options {
return &Options{
OutputPaths: []string{defaultOutputPath},
ErrorOutputPaths: []string{defaultErrorOutputPath},
RotationMaxSize: defaultRotationMaxSize,
RotationMaxAge: defaultRotationMaxAge,
RotationMaxBackups: defaultRotationMaxBackups,
defaultOutputLevels: "default:info,grpc:none",
stackTraceLevels: DefaultScopeName + ":" + levelToString[defaultStackTraceLevel],
logGRPC: false,
useStackdriverFormat: false,
}
}
// WithStackdriverLoggingFormat configures logging output to match Stackdriver structured logging conventions.
func (o *Options) WithStackdriverLoggingFormat() *Options {
o.useStackdriverFormat = true
return o
}
// WithTeeToUDS configures a parallel logging pipeline that writes logs to a server over UDS.
// addr is the socket that the server listens on, and path is the HTTP path that process the log message.
func (o *Options) WithTeeToUDS(addr, path string) *Options {
return o.WithExtension(func(c zapcore.Core) (zapcore.Core, func() error, error) {
return teeToUDSServer(c, addr, path), func() error { return nil }, nil
})
}
// Extension provides an extension mechanism for logs.
// This is essentially like https://pkg.go.dev/golang.org/x/exp/slog#Handler.
// This interface should be considered unstable; we will likely swap it for slog in the future and not expose zap internals.
// Returns a modified Core interface, and a Close() function.
type Extension func(c zapcore.Core) (zapcore.Core, func() error, error)
func (o *Options) WithExtension(e Extension) *Options {
o.extensions = append(o.extensions, e)
return o
}
// SetDefaultOutputLevel sets the minimum log output level for a given scope.
// This can be overwritten by flags
func (o *Options) SetDefaultOutputLevel(scope string, level Level) {
sl := scope + ":" + levelToString[level]
levels := strings.Split(o.defaultOutputLevels, ",")
if scope == DefaultScopeName {
// see if we have an entry without a scope prefix (which represents the default scope)
for i, ol := range levels {
if !strings.Contains(ol, ":") {
levels[i] = sl
o.defaultOutputLevels = strings.Join(levels, ",")
return
}
}
}
prefix := scope + ":"
for i, ol := range levels {
if strings.HasPrefix(ol, prefix) {
levels[i] = sl
o.defaultOutputLevels = strings.Join(levels, ",")
return
}
}
levels = append(levels, sl)
o.defaultOutputLevels = strings.Join(levels, ",")
}
func convertScopedLevel(sl string) (string, Level, error) {
var s string
var l string
pieces := strings.Split(sl, ":")
if len(pieces) == 1 {
s = DefaultScopeName
l = pieces[0]
} else if len(pieces) == 2 {
s = pieces[0]
l = pieces[1]
} else {
return "", NoneLevel, fmt.Errorf("invalid output level format '%s'", sl)
}
level, ok := stringToLevel[l]
if !ok {
return "", NoneLevel, fmt.Errorf("invalid output level '%s'", sl)
}
return s, level, nil
}
// AttachCobraFlags attaches a set of Cobra flags to the given Cobra command.
//
// Cobra is the command-line processor that Istio uses. This command attaches
// the necessary set of flags to expose a CLI to let the user control all
// logging options.
func (o *Options) AttachCobraFlags(cmd *cobra.Command) {
o.AttachFlags(
cmd.PersistentFlags().StringArrayVar,
cmd.PersistentFlags().StringVar,
cmd.PersistentFlags().IntVar,
cmd.PersistentFlags().BoolVar)
}
// AttachFlags allows attaching of flags through a set of lambda functions.
func (o *Options) AttachFlags(
stringArrayVar func(p *[]string, name string, value []string, usage string),
stringVar func(p *string, name string, value string, usage string),
intVar func(p *int, name string, value int, usage string),
boolVar func(p *bool, name string, value bool, usage string),
) {
stringArrayVar(&o.OutputPaths, "log_target", o.OutputPaths,
"The set of paths where to output the log. This can be any path as well as the special values stdout and stderr")
stringVar(&o.RotateOutputPath, "log_rotate", o.RotateOutputPath,
"The path for the optional rotating log file")
intVar(&o.RotationMaxAge, "log_rotate_max_age", o.RotationMaxAge,
"The maximum age in days of a log file beyond which the file is rotated (0 indicates no limit)")
intVar(&o.RotationMaxSize, "log_rotate_max_size", o.RotationMaxSize,
"The maximum size in megabytes of a log file beyond which the file is rotated")
intVar(&o.RotationMaxBackups, "log_rotate_max_backups", o.RotationMaxBackups,
"The maximum number of log file backups to keep before older files are deleted (0 indicates no limit)")
boolVar(&o.JSONEncoding, "log_as_json", o.JSONEncoding,
"Whether to format output as JSON or in plain console-friendly format")
levelListString := fmt.Sprintf("[%s, %s, %s, %s, %s, %s]",
levelToString[DebugLevel],
levelToString[InfoLevel],
levelToString[WarnLevel],
levelToString[ErrorLevel],
levelToString[FatalLevel],
levelToString[NoneLevel])
allScopes := Scopes()
if len(allScopes) > 1 {
keys := make([]string, 0, len(allScopes))
for name := range allScopes {
keys = append(keys, name)
}
keys = append(keys, OverrideScopeName)
sort.Strings(keys)
s := strings.Join(keys, ", ")
stringVar(&o.outputLevels, "log_output_level", o.outputLevels,
fmt.Sprintf("Comma-separated minimum per-scope logging level of messages to output, in the form of "+
"<scope>:<level>,<scope>:<level>,... where scope can be one of [%s] and level can be one of %s",
s, levelListString))
stringVar(&o.stackTraceLevels, "log_stacktrace_level", o.stackTraceLevels,
fmt.Sprintf("Comma-separated minimum per-scope logging level at which stack traces are captured, in the form of "+
"<scope>:<level>,<scope:level>,... where scope can be one of [%s] and level can be one of %s",
s, levelListString))
stringVar(&o.logCallers, "log_caller", o.logCallers,
fmt.Sprintf("Comma-separated list of scopes for which to include caller information, scopes can be any of [%s]", s))
} else {
stringVar(&o.outputLevels, "log_output_level", o.outputLevels,
fmt.Sprintf("The minimum logging level of messages to output, can be one of %s",
levelListString))
stringVar(&o.stackTraceLevels, "log_stacktrace_level", o.stackTraceLevels,
fmt.Sprintf("The minimum logging level at which stack traces are captured, can be one of %s",
levelListString))
stringVar(&o.logCallers, "log_caller", o.logCallers,
"Comma-separated list of scopes for which to include called information, scopes can be any of [default]")
}
// NOTE: we don't currently expose a command-line option to control ErrorOutputPaths since it
// seems too esoteric.
}