1klog
2====
3
4klog is a permanent fork of https://github.com/golang/glog.
5
6## Why was klog created?
7
8The decision to create klog was one that wasn't made lightly, but it was necessary due to some
9drawbacks that are present in [glog](https://github.com/golang/glog). Ultimately, the fork was created due to glog not being under active development; this can be seen in the glog README:
10
11> The code in this repo [...] is not itself under development
12
13This makes us unable to solve many use cases without a fork. The factors that contributed to needing feature development are listed below:
14
15 * `glog` [presents a lot "gotchas"](https://github.com/kubernetes/kubernetes/issues/61006) and introduces challenges in containerized environments, all of which aren't well documented.
16 * `glog` doesn't provide an easy way to test logs, which detracts from the stability of software using it
17 * A long term goal is to implement a logging interface that allows us to add context, change output format, etc.
18
19Historical context is available here:
20
21 * https://github.com/kubernetes/kubernetes/issues/61006
22 * https://github.com/kubernetes/kubernetes/issues/70264
23 * https://groups.google.com/forum/#!msg/kubernetes-sig-architecture/wCWiWf3Juzs/hXRVBH90CgAJ
24 * https://groups.google.com/forum/#!msg/kubernetes-dev/7vnijOMhLS0/1oRiNtigBgAJ
25
26## Release versioning
27
28Semantic versioning is used in this repository. It contains several Go modules
29with different levels of stability:
30- `k8s.io/klog/v2` - stable API, `vX.Y.Z` tags
31- `examples` - no stable API, no tags, no intention to ever stabilize
32
33Exempt from the API stability guarantee are items (packages, functions, etc.)
34which are marked explicitly as `EXPERIMENTAL` in their docs comment. Those
35may still change in incompatible ways or get removed entirely. This can only
36be used for code that is used in tests to avoid situations where non-test
37code from two different Kubernetes dependencies depends on incompatible
38releases of klog because an experimental API was changed.
39
40----
41
42How to use klog
43===============
44- Replace imports for `"github.com/golang/glog"` with `"k8s.io/klog/v2"`
45- Use `klog.InitFlags(nil)` explicitly for initializing global flags as we no longer use `init()` method to register the flags
46- You can now use `log_file` instead of `log_dir` for logging to a single file (See `examples/log_file/usage_log_file.go`)
47- If you want to redirect everything logged using klog somewhere else (say syslog!), you can use `klog.SetOutput()` method and supply a `io.Writer`. (See `examples/set_output/usage_set_output.go`)
48- For more logging conventions (See [Logging Conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md))
49- See our documentation on [pkg.go.dev/k8s.io](https://pkg.go.dev/k8s.io/klog).
50
51**NOTE**: please use the newer go versions that support semantic import versioning in modules, ideally go 1.11.4 or greater.
52
53### Coexisting with klog/v2
54
55See [this example](examples/coexist_klog_v1_and_v2/) to see how to coexist with both klog/v1 and klog/v2.
56
57### Coexisting with glog
58This package can be used side by side with glog. [This example](examples/coexist_glog/coexist_glog.go) shows how to initialize and synchronize flags from the global `flag.CommandLine` FlagSet. In addition, the example makes use of stderr as combined output by setting `alsologtostderr` (or `logtostderr`) to `true`.
59
60## Community, discussion, contribution, and support
61
62Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).
63
64You can reach the maintainers of this project at:
65
66- [Slack](https://kubernetes.slack.com/messages/klog)
67- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-architecture)
68
69### Code of conduct
70
71Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
72
73----
74
75glog
76====
77
78Leveled execution logs for Go.
79
80This is an efficient pure Go implementation of leveled logs in the
81manner of the open source C++ package
82 https://github.com/google/glog
83
84By binding methods to booleans it is possible to use the log package
85without paying the expense of evaluating the arguments to the log.
86Through the -vmodule flag, the package also provides fine-grained
87control over logging at the file level.
88
89The comment from glog.go introduces the ideas:
90
91 Package glog implements logging analogous to the Google-internal
92 C++ INFO/ERROR/V setup. It provides functions Info, Warning,
93 Error, Fatal, plus formatting variants such as Infof. It
94 also provides V-style logging controlled by the -v and
95 -vmodule=file=2 flags.
96
97 Basic examples:
98
99 glog.Info("Prepare to repel boarders")
100
101 glog.Fatalf("Initialization failed: %s", err)
102
103 See the documentation of the V function for an explanation
104 of these examples:
105
106 if glog.V(2) {
107 glog.Info("Starting transaction...")
108 }
109
110 glog.V(2).Infoln("Processed", nItems, "elements")
111
112
113The repository contains an open source version of the log package
114used inside Google. The master copy of the source lives inside
115Google, not here. The code in this repo is for export only and is not itself
116under development. Feature requests will be ignored.
117
118Send bug reports to golang-nuts@googlegroups.com.
View as plain text