H4HIP: Enhanced logging library for Helm CLI

hips/hip-9999.md

@@ -0,0 +1,96 @@
+---
+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 and SDK to enhance logging capabilities for troubleshooting, development, and debugging. By using newer logging features such as log formatting and different log levels, developers and CLI users gain flexibility when deciding how much logging information they want to consume, and in what format.
+
+The HIP also introduces the ability for SDK users to use their own logging library with the SDK. Users will be able to provide a logger implementing `slog.Handler` interface, allowing them to consume instrumented logs in the SDK.
+
+## Motivation
+
+The current logging mechanism in Helm CLI and SDK 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 Helm code with clear and consistent logging conventions for contributors, as well as consumers of CLI and SDK logs.
+- Inflexibility using a different logging library to what the SDK uses. There is no way, in code, to have client loggers consume logs produced by the SDK
+
+The proposed solution addresses these gaps by integrating a logging library that supports log levels and structured output, as well as a widely supported logger implementation interface for SDK users to consume.
+
+## Rationale
+
+The following libraries were evaluated:
+
+1. **`slog`:**
+   - Provides log levels (`info`, `debug`, `error`, `warning`). More levels can be added
+   - Offers structured logging.
+   - Lightweight and straightforward to integrate.
+   - Is part of Go standard library
+   - Has `slog.Handler` interface that other logger implementations can implement to be `slog` compatible
+
+2. **`klog`:**
+   - 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.
+   - Allows getting instrumented Kubernetes client library
+   - Its an external library, hence introducing a dependency
+
+3. **`logr`**
+   - Library defining interfaces for logger implementations and libraries expecting loggers that implement these APIs. `klog`, `slog`, `log` and many others are compatible with `logr`.
+   - Provides log levels also verbosity levels
+   - Its an external library, hence introducing a dependency
+   - Has `logr.Handler` interface that other logger implementations can implement to be `logr` compatible
+
+While these libraries meet all the requirements we want, `slog` is the preferred choice here. It provides all functionality that the other choices have but stands out since it has a wider adoption given that its part of Go standard library. This will be benefitial to SDK users who have their existing logger implementations present. They would either implement `slog.Handler` interface or add a dependency of an existing adapter logger implementation.
+
+## Specification
+
+- Helm will instrument `debug`, `info`, `warning` and `error` log levels. These log levels will enable filtering of logs.
+- Logs will be written to `stderr` by the Helm CLI client. `stdout` will be left for output from operations. SDK users would choose where to write logs to through configuring the logger they pass to the SDK.
+- Ability to allow users to configure log levels and formatting through CLI flags or environment variables.
+- 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 log or not.
+- When invoking plugins and post-renderers, `HELM_LOG_LEVEL` and `HELM_LOG_FORMAT` environment variables would be set, allowing them to output the appropriate amount of logs and format to stderr.
+- There will be structured logging with two options. Raw text for humans to view, and JSON formatting that machines can consume.
+- Ability for SDK users to override the default logger implementation. The SDK will expect at logger that implements `slog.Handler` interface.
+
+### Example:
+
+TODO: To be added once specification is agreed
+
+## Backwards Compatibility
+
+The current logging system, Golang's `log` package will be replaced by `slog`.
+
+## 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 log levels and formats.
+   - Document conventions of how to instrument logs. Specifically, what information should be in what log level. Also document that the SDK does not log errors.
+   - Example for SDK users of how to override the default logger with their own implementation. For loggers that do not implement `slog.Handler`, document an example of how this can be done.
+   - Document how plugins and post-renderers can inherit log levels and formatting from helm CLI client.
+
+2. **CLI help text:**
+   - Use Helm 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)