H4HIP: Enhanced logging library for Helm CLI #372
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| hip: 9999 | ||
| title: "Enhanced logging library for Helm CLI" | ||
| authors: [ "Evans Mungai <[email protected]>" ] | ||
| created: "2024-11-22" | ||
| type: "feature" | ||
| status: "draft" | ||
| --- | ||
|
|
||
| ## Abstract | ||
|
|
||
| This proposal introduces an improved logging library for Helm CLI to enhance logging capabilities for troubleshooting, development, and debugging. By using newer logging features such as log formatting, different log levels and verbosity levels, developers and CLI users gain flexibility when deciding how much logging information they want to consume, and in what format. | ||
|
|
||
| ## Motivation | ||
|
|
||
| The current logging mechanism in Helm CLI lacks granularity and structure. Users and developers face difficulties when: | ||
|
|
||
| - Troubleshooting Helm CLI commands due to inability to increase the details that can get logged. More logs come in handy when submitting bug reports for example. | ||
| - Instrumenting code with clear and consistent logging conventions for contributors, as well as consumers of CLI logs. | ||
|
Comment on lines
+18
to
+19
There was a problem hiding this comment. Also, SDK users integrating with Helm have to use Helm's custom logging mechanism. This is an integration problem for users (e.g., Flux) |
||
|
|
||
| The proposed solution addresses these gaps by integrating a logging library that supports log levels, verbosity, and structured output. | ||
|
|
||
| ## Rationale | ||
|
|
||
| Two libraries were evaluated: | ||
|
|
||
| 1. **`slog`:** | ||
| - Provides log levels (`info`, `debug`, `error`, `warning`). | ||
|
There was a problem hiding this comment. Note, it's fairly easy to add levels if an app wants to use more. The Go docs provide an example. |
||
| - Offers structured logging. | ||
| - Lightweight and straightforward to integrate. | ||
| - Is part of the standard library | ||
|
|
||
| 2. **`klog`:** | ||
|
There was a problem hiding this comment. In addition to klog there is logr, an interface that klog suffices. Can you add that in. |
||
| - Provides log levels and also verbosity levels, enabling more granular control. Verbosity level controls the amount of detail in logs, enabling users to filter messages based on their importance or relevance. | ||
| - Well-aligned with Kubernetes development standards. | ||
| - Allows getting instrumented Kubernetes client library. | ||
|
|
||
| While both libraries meet the basic requirements, `klog` offers richer features for developers familiar with Kubernetes' logging patterns, making it the preferred choice for this proposal. | ||
|
There was a problem hiding this comment. There are two parts to Helm. There is the SDK and then the client that uses the SDK. The SDK shouldn't use an implementation of logging. It should accept a logger from any application that uses it and follows the right interface. So, the SDK should use either Note, SDK users may not be developers familiar with Kubernetes. There will be people familiar with and those not familiar with it. Then there is the Helm client (a.k.a CLI). This should pick an implementation. It could be slog, klog, zap, or something else. Note, klog appears to support the slog interface (see this example). We need to make decisions on both of these. If we go the klog route for the Helm Client we should document the log levels to use and what they mean. There is no common clarity on what levels to use for what. This is one of the weakness of this model. What level should you set for what purposes? |
||
|
|
||
| ## Specification | ||
|
|
||
| - Helm SDK should not be instrumented with error logs. Instead, errors ought to be returned. Any logging of such errors should be left to clients to choose whether to print or not. | ||
| - Verbosity levels to enable filtering of logs based on verbosity levels. Lower verbosity levels would be used for major operations in the flow control. __TODO: Should I specify actual numbers or would that be too prescriptive?__ | ||
| - When invoking plugins and post-renderers, `HELM_LOG_LEVEL` and `HELM_VERBOSITY_LEVEL` environment variables would be set, allowing them to output the appropriate amount of logs to stderr | ||
| - Structured logging with two options Raw text for humans to view, and JSON formatting that machines can consume. | ||
| - Ability to allow users to configure log levels, verbosity and formatting through CLI flags or environment variables. | ||
|
|
||
| ### Example: | ||
|
|
||
| TODO: To be added once specification is agreed | ||
|
|
||
| ## Backwards Compatibility | ||
|
|
||
| The current logging system, Golang's `log` package will be replaced by `klog`. | ||
|
|
||
| ## Security Implications | ||
|
|
||
|
|
||
| ## How to Teach This | ||
|
|
||
| 1. **Documentation Updates:** | ||
| - Provide examples of using the new logging features in the Helm documentation. | ||
| - Include a section on how to configure verbosity, log levels and formats. | ||
| - Document conventions of how to instrument logs. Specifically, what information should be in what verbosity level. | ||
|
|
||
| 2. **CLI help text:** | ||
| - Use CLI help messages (`helm --help`) to inform users about the new logging options. | ||
|
|
||
| ## Reference Implementation | ||
|
|
||
|
|
||
| ## Rejected Ideas | ||
|
|
||
| 1. **Sticking with the current logging system:** | ||
| - Rejected due to lack of flexibility and limited usefulness for debugging. | ||
|
|
||
| ## Open Issues | ||
|
|
||
|
|
||
| ## References | ||
|
|
||
| - [Go’s slog Documentation](https://pkg.go.dev/log/slog) | ||
| - [klog Documentation](https://pkg.go.dev/k8s.io/klog/v2) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It might be useful to call out the SDK users and how they can integrate with Helm in a standard way.