132 lines
5.8 KiB
Markdown
132 lines
5.8 KiB
Markdown
# cse-go-logging
|
|
Common golang logging module for use in CSE Go applications
|
|
|
|
## Overview
|
|
|
|
This library will help you define a consistent logging experience within your Go applications. In a simple statement...
|
|
|
|
* This library will define a **Log Message**
|
|
* That is at a **Log Level**
|
|
* Which is formatted in a defined **Log Format**
|
|
* And forwarded to a **Log Destination**
|
|
|
|
This module is wrapper around Uber's Zap package. It serves more as a quick, consistent configuration than to add any additional functionality. For more details on how to use Zap, you can read the [Uber Documentation](https://pkg.go.dev/go.uber.org/zap)
|
|
|
|
### Additional Convenience Methods
|
|
|
|
I, for one, get annoyed with the following code:
|
|
|
|
~~~
|
|
MyObject, err := SomeInitializer(param1, param2)
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
~~~
|
|
|
|
Those last three lines are extremely common, and clutter up the code and really do not add to readability. So, I created a set of convenience methods where you can replace the error handling with <ErrorLevel>OnError(err) and have it log your error, and panic or fatal automatically. The above code now becomes:
|
|
|
|
~~~
|
|
MyObject, err := SomeInitializer(param1, param2)
|
|
PanicOnError(err)
|
|
~~~
|
|
|
|
Its just athletics, but code is cleaner
|
|
|
|
|
|
### Process Cleanup
|
|
|
|
Another issue this library is trying to make simpler is proper shutdown on Fatal and Panic.
|
|
|
|
In many ways GO follows functional not object-oriented patterns. If an object is created, and defer() was defined, it can have unwanted side effects. So, I often avoid it unless the object is created, used, then immediately discarded. So how to we safely handle longer running objects.
|
|
|
|
This module has a solution, and you can use piggyback this in your own programs if you like.
|
|
|
|
There is a struct called AtExit that is defined, and it has two methods on it:
|
|
|
|
* Register
|
|
* Cleanup
|
|
|
|
Register takes one parameter, a function name. The call will register that function to be called any time you run a PanicOnError or FatalOnError. The Cleanup function will call all functions "Registered" before issuing the fatal/panic call.
|
|
|
|
Usage Example:
|
|
~~~
|
|
var (
|
|
db <pointer to some database connector>
|
|
)
|
|
|
|
func init() {
|
|
db = // Insert your favorite database connect string here
|
|
|
|
AtExit.Register(ShutDownDbConnection)
|
|
}
|
|
|
|
func ShutDownDbConnection() {
|
|
logger.ErrorOnError(db.close())
|
|
}
|
|
~~~
|
|
|
|
### Log Message
|
|
|
|
A log message, simply put will contain
|
|
|
|
* a time and date stamp
|
|
* a string indicating the Log Level
|
|
* a Log message
|
|
|
|
Optional items that may appear include
|
|
|
|
* A locator for where the message was requested in the code
|
|
* Name Value pairs the code may want you to note
|
|
* A stack trace giving even more detailed trace for error handling
|
|
|
|
### Log Level
|
|
|
|
As with many level based logging libraries, this library will define the following log levels:
|
|
|
|
* **Debug:** Recommendation: Tracing variable Values {user: Joe}
|
|
* **Info:** Recommendation: Dev status message {DB Connection successful}
|
|
* **Warn:** Recommendation: Non-Critical Errors {Got string, expected int, using 0}
|
|
* **Error:** Recommendation: Serious error but not enough to stop program execution {Network Not Found, 404 errors}
|
|
* **Fatal:** Recommendation: Serious Errors, program exist with error code 1
|
|
* **Panic:** Recommendation: Full panic mode, {divide by 0}
|
|
|
|
## Log Format
|
|
|
|
In this library, there will be two different output formats
|
|
|
|
* **Text:** Single line per message with space delimiters
|
|
* **JSON:** JSON format for easy automated processing
|
|
|
|
Example of Text Log Format:
|
|
~~~
|
|
2024-01-25T12:33:25.613-0700 INFO cse-go-logging/logging_test.go:25 This is my log message
|
|
~~~
|
|
|
|
Example of JSON Log Format:
|
|
~~~
|
|
{
|
|
"level": "error",
|
|
"ts": "2024-01-25T13:10:01.025-0700",
|
|
"caller": "cse-go-logging/logging_test.go:25",
|
|
"msg": "This is my log message",
|
|
"stacktrace": "cse-go-logging.(*LoggingTestSuite).Test_Placeholder\n\t/Users/a846682/GolandProjects/cse-go-logging/logging_test.go:25\nreflect.Value.call\n\t/Users/a846682/.asdf/installs/golang/1.21.6/go/src/reflect/value.go:596\nreflect.Value.Call\n\t/Users/a846682/.asdf/installs/golang/1.21.6/go/src/reflect/value.go:380\ngithub.com/stretchr/testify/suite.Run.func1\n\t/Users/a846682/.asdf/installs/golang/1.21.6/packages/pkg/mod/github.com/stretchr/testify@v1.8.1/suite/suite.go:175\ntesting.tRunner\n\t/Users/a846682/.asdf/installs/golang/1.21.6/go/src/testing/testing.go:1595"
|
|
}
|
|
~~~
|
|
|
|
### Log Destination
|
|
|
|
Depending on the **Log Environment** you have configured your code to use, the log output will be sent to one of three different destinations:
|
|
|
|
* **StdErr:** Development, Debug, and Production logs will send messages to standard error. These should appear on your output console within your machine
|
|
* **LogFile:** Debug and Testing logs will create a file in your running directory named */log/debug*
|
|
* If you are running with a Testing log, the library will not use your live file system, but instead will use a memory map backed filesystem called LogFS and will exist as long as the test suite is running.
|
|
|
|
## Log Environments
|
|
|
|
This library defines four predefined environments for your logging needs:
|
|
|
|
* **Development:** for normal development operations. Logs will be text based, and log Info and higher messages. Output will be to StdErr
|
|
* **Debug:** To increase the verbosity of logging, a Debug environment will also include Debug log messages, and will capture all logs to a *logs/debug* file within your working directory. In addition, stack traces will be turned on. So, errors can be more easily tracked.
|
|
* **Testing:** This environment will operate exactly like Debug, except that it will not send logs to stderr, and will attach a memory backed file system that /logs/debug will be written to. This allows tests to easily pick up the output of log messages and test for proper logging
|
|
* **Production:** Unlike the other environments, Production logs are JSON formatted.
|