1 /* 2 Copyright 2021 The Kubernetes Authors. 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 */ 16 17 package v1 18 19 import ( 20 "encoding/json" 21 "fmt" 22 23 "k8s.io/apimachinery/pkg/api/resource" 24 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 25 ) 26 27 // Supported output formats. 28 const ( 29 // DefaultLogFormat is the traditional klog output format. 30 DefaultLogFormat = "text" 31 32 // JSONLogFormat emits each log message as a JSON struct. 33 JSONLogFormat = "json" 34 ) 35 36 // The alpha or beta level of structs is the highest stability level of any field 37 // inside it. Feature gates will get checked during LoggingConfiguration.ValidateAndApply. 38 39 // LoggingConfiguration contains logging options. 40 type LoggingConfiguration struct { 41 // Format Flag specifies the structure of log messages. 42 // default value of format is `text` 43 Format string `json:"format,omitempty"` 44 // Maximum time between log flushes. 45 // If a string, parsed as a duration (i.e. "1s") 46 // If an int, the maximum number of nanoseconds (i.e. 1s = 1000000000). 47 // Ignored if the selected logging backend writes log messages without buffering. 48 FlushFrequency TimeOrMetaDuration `json:"flushFrequency"` 49 // Verbosity is the threshold that determines which log messages are 50 // logged. Default is zero which logs only the most important 51 // messages. Higher values enable additional messages. Error messages 52 // are always logged. 53 Verbosity VerbosityLevel `json:"verbosity"` 54 // VModule overrides the verbosity threshold for individual files. 55 // Only supported for "text" log format. 56 VModule VModuleConfiguration `json:"vmodule,omitempty"` 57 // [Alpha] Options holds additional parameters that are specific 58 // to the different logging formats. Only the options for the selected 59 // format get used, but all of them get validated. 60 // Only available when the LoggingAlphaOptions feature gate is enabled. 61 Options FormatOptions `json:"options,omitempty"` 62 } 63 64 // TimeOrMetaDuration is present only for backwards compatibility for the 65 // flushFrequency field, and new fields should use metav1.Duration. 66 type TimeOrMetaDuration struct { 67 // Duration holds the duration 68 Duration metav1.Duration 69 // SerializeAsString controls whether the value is serialized as a string or an integer 70 SerializeAsString bool `json:"-"` 71 } 72 73 func (t TimeOrMetaDuration) MarshalJSON() ([]byte, error) { 74 if t.SerializeAsString { 75 return t.Duration.MarshalJSON() 76 } else { 77 // Marshal as integer for backwards compatibility 78 return json.Marshal(t.Duration.Duration) 79 } 80 } 81 82 func (t *TimeOrMetaDuration) UnmarshalJSON(b []byte) error { 83 if len(b) > 0 && b[0] == '"' { 84 // string values unmarshal as metav1.Duration 85 t.SerializeAsString = true 86 return json.Unmarshal(b, &t.Duration) 87 } 88 t.SerializeAsString = false 89 if err := json.Unmarshal(b, &t.Duration.Duration); err != nil { 90 return fmt.Errorf("invalid duration %q: %w", string(b), err) 91 } 92 return nil 93 } 94 95 // FormatOptions contains options for the different logging formats. 96 type FormatOptions struct { 97 // [Alpha] Text contains options for logging format "text". 98 // Only available when the LoggingAlphaOptions feature gate is enabled. 99 Text TextOptions `json:"text,omitempty"` 100 // [Alpha] JSON contains options for logging format "json". 101 // Only available when the LoggingAlphaOptions feature gate is enabled. 102 JSON JSONOptions `json:"json,omitempty"` 103 } 104 105 // TextOptions contains options for logging format "text". 106 type TextOptions struct { 107 OutputRoutingOptions `json:",inline"` 108 } 109 110 // JSONOptions contains options for logging format "json". 111 type JSONOptions struct { 112 OutputRoutingOptions `json:",inline"` 113 } 114 115 // OutputRoutingOptions contains options that are supported by both "text" and "json". 116 type OutputRoutingOptions struct { 117 // [Alpha] SplitStream redirects error messages to stderr while 118 // info messages go to stdout, with buffering. The default is to write 119 // both to stdout, without buffering. Only available when 120 // the LoggingAlphaOptions feature gate is enabled. 121 SplitStream bool `json:"splitStream,omitempty"` 122 // [Alpha] InfoBufferSize sets the size of the info stream when 123 // using split streams. The default is zero, which disables buffering. 124 // Only available when the LoggingAlphaOptions feature gate is enabled. 125 InfoBufferSize resource.QuantityValue `json:"infoBufferSize,omitempty"` 126 } 127 128 // VModuleConfiguration is a collection of individual file names or patterns 129 // and the corresponding verbosity threshold. 130 type VModuleConfiguration []VModuleItem 131 132 // VModuleItem defines verbosity for one or more files which match a certain 133 // glob pattern. 134 type VModuleItem struct { 135 // FilePattern is a base file name (i.e. minus the ".go" suffix and 136 // directory) or a "glob" pattern for such a name. It must not contain 137 // comma and equal signs because those are separators for the 138 // corresponding klog command line argument. 139 FilePattern string `json:"filePattern"` 140 // Verbosity is the threshold for log messages emitted inside files 141 // that match the pattern. 142 Verbosity VerbosityLevel `json:"verbosity"` 143 } 144 145 // VerbosityLevel represents a klog or logr verbosity threshold. 146 type VerbosityLevel uint32 147