diff --git a/RULES.md b/RULES.md index 1c1b4f5..bbda28e 100644 --- a/RULES.md +++ b/RULES.md @@ -24,6 +24,7 @@ Any Config structs with environment variables should have their docstrings match where the required and default fields are only present if relevant to that variable The wiki is located at ~/projects/golib-wiki and should be laid out as follows: +- Link to wiki page from the Home page - Title and description with version number - Installation - Key Concepts and features @@ -40,5 +41,6 @@ The wiki is located at ~/projects/golib-wiki and should be laid out as follows: Any changes to existing features or additional features implemented should have tests created and/or updated 3. Version control +Version numbers are specified using git tags. Do not change version numbers. When updating documentation, append the branch name to the version number. Changes made to the golib-wiki repo should be made under the same branch name as the changes made in this repo diff --git a/hlog/README.md b/hlog/README.md new file mode 100644 index 0000000..6f58543 --- /dev/null +++ b/hlog/README.md @@ -0,0 +1,73 @@ +# HLog - v0.10.1-hlogdoc + +A structured logging package for Go built on top of [zerolog](https://github.com/rs/zerolog). HLog provides simple configuration via environment variables, flexible output options, and automatic log file management. + +## Features + +- Multiple output modes: console, file, or both simultaneously +- Configurable log levels: trace, debug, info, warn, error, fatal, panic +- Environment variable-based configuration with ConfigFromEnv +- Automatic log file management with append or overwrite modes +- Built on zerolog for high performance and structured logging +- Error stack trace support via pkg/errors integration +- Unix timestamp format +- Console-friendly output formatting +- Multi-writer support for simultaneous console and file output + +## Installation + +```bash +go get git.haelnorr.com/h/golib/hlog +``` + +## Quick Start + +```go +package main + +import ( + "log" + "os" + + "git.haelnorr.com/h/golib/hlog" +) + +func main() { + // Load configuration from environment variables + cfg, err := hlog.ConfigFromEnv() + if err != nil { + log.Fatal(err) + } + + // Create a new logger + logger, err := hlog.NewLogger(cfg, os.Stdout) + if err != nil { + log.Fatal(err) + } + defer logger.CloseLogFile() + + // Start logging + logger.Info().Msg("Application started") + logger.Debug().Str("user", "john").Msg("User logged in") + logger.Error().Err(err).Msg("Something went wrong") +} +``` + +## Documentation + +For detailed documentation, see the [HLog Wiki](https://git.haelnorr.com/h/golib-wiki/HLog). + +Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hlog). + +## License + +This project is licensed under the MIT License - see the LICENSE file for details. + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +## Related Projects + +- [env](https://git.haelnorr.com/h/golib/env) - Environment variable helper used by hlog for configuration +- [zerolog](https://github.com/rs/zerolog) - The underlying logging library diff --git a/hlog/doc.go b/hlog/doc.go index 06820e3..021dfad 100644 --- a/hlog/doc.go +++ b/hlog/doc.go @@ -24,18 +24,22 @@ // // # Configuration // -// hlog can be configured via environment variables: +// hlog can be configured via environment variables using ConfigFromEnv: // -// LOG_LEVEL=info # trace, debug, info, warn, error, fatal, panic (default: info) -// LOG_OUTPUT=console # console, file, or both (default: console) -// LOG_DIR=/var/log/app # Required when LOG_OUTPUT is "file" or "both" +// LOG_LEVEL=info # trace, debug, info, warn, error, fatal, panic (default: info) +// LOG_OUTPUT=console # console, file, or both (default: console) +// LOG_DIR=/var/log/app # Required when LOG_OUTPUT is "file" or "both" +// LOG_FILE_NAME=server.log # Required when LOG_OUTPUT is "file" or "both" +// LOG_APPEND=true # Append to existing file or overwrite (default: true) // // Or programmatically: // // cfg := &hlog.Config{ -// LogLevel: hlog.InfoLevel, -// LogOutput: "both", -// LogDir: "/var/log/myapp", +// LogLevel: hlog.InfoLevel, +// LogOutput: "both", +// LogDir: "/var/log/myapp", +// LogFileName: "server.log", +// LogAppend: true, // } // // # Log Levels @@ -52,13 +56,27 @@ // # Output Modes // // - console: Logs to the provided io.Writer (typically os.Stdout or os.Stderr) -// - file: Logs to a file named "server.log" in the configured directory -// - both: Logs to both console and file simultaneously +// - file: Logs to a file in the configured directory +// - both: Logs to both console and file simultaneously using zerolog.MultiLevelWriter // // # File Management // -// When using file output, hlog creates a file named "server.log" in the -// specified directory. The file is opened in append mode, so logs persist -// across application restarts. Remember to call CloseLogFile() when shutting -// down your application to ensure all logs are flushed. +// When using file output, hlog creates a file with the specified name in the +// configured directory. The file can be opened in append mode (default) to +// preserve logs across application restarts, or in overwrite mode to start +// fresh each time. Remember to call CloseLogFile() when shutting down your +// application to ensure all logs are flushed to disk. +// +// # Error Stack Traces +// +// hlog automatically configures zerolog to include stack traces for errors +// wrapped with github.com/pkg/errors. This provides detailed error context +// when using errors.Wrap or errors.WithStack. +// +// # Integration +// +// hlog integrates with: +// - git.haelnorr.com/h/golib/env: For environment variable configuration +// - github.com/rs/zerolog: The underlying logging implementation +// - github.com/pkg/errors: For error stack trace support package hlog