Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fogfish/logger
Logger for serverless Golang applications
https://github.com/fogfish/logger
aws-cloudwatch aws-cloudwatch-logs golang golang-library golang-slog golang-slog-handler
Last synced: 3 months ago
JSON representation
Logger for serverless Golang applications
- Host: GitHub
- URL: https://github.com/fogfish/logger
- Owner: fogfish
- License: mit
- Created: 2021-08-05T21:08:52.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-14T09:54:06.000Z (4 months ago)
- Last Synced: 2024-10-18T16:26:00.695Z (3 months ago)
- Topics: aws-cloudwatch, aws-cloudwatch-logs, golang, golang-library, golang-slog, golang-slog-handler
- Language: Go
- Homepage:
- Size: 43 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
logger
logging config for Golang's slog
---
logger is a configuration for Golang [slog](https://pkg.go.dev/log/slog) developed for easy to use within serverless applications (e.g. logging to AWS CloudWatch).
## Inspiration
The library outputs log messages as JSON object. The configuration enforces output filename and line of the log statement to facilitate further analysis.
```
2023-10-26 19:12:44.709 +0300 EEST:
{
"level": "INFO",
"source": {
"function": "main.example",
"file": "example.go",
"line": 143
},
"msg": "some output",
"key": "val",
...
}
```
The configuration inherits best practices of telecom application, it enhances existing `Debug`, `Info`, `Warn` and `Error` levels with 3 additional, making fine grained logging with 7 levels:
1. `EMERGENCY`, `EMR`: system is unusable, panic execution of current routine or application, it is not possible to gracefully terminate it.
2. `CRITICAL`, `CRT`: system is failed, response actions must be taken immediately, the application is not able to execute correctly but still able to gracefully exit.
3. `ERROR`, `ERR`: system is failed, unable to recover from error. The failure do not have global catastrophic impacts but local functionality is impaired, incorrect result is returned.
4. `WARN`, `WRN`: system is failed, unable to recover, degraded functionality. The failure is ignored and application still capable to deliver incomplete but correct results.
5. `NOTICE`, `NTC`: system is failed, error is recovered, no impact.
6. `INFO`, `INF`: output informative status about system.
7. `DEBUG`, `DEB`: output debug status about system.
## Getting started
The latest version of the configuration is available at `main` branch of this repository. All development, including new features and bug fixes, take place on the `main` branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.
Import configuration and start logging using `slog` api. The default config is optimized for logging within Serverless application.
```go
import (
"log/slog"
_ "github.com/fogfish/logger/v3"
)
// 2023-10-26 19:12:44.709 +0300 EEST:
// {
// "level": "INFO",
// "source": {
// "function": "main.example",
// "file": "example.go",
// "line": 143
// },
// "msg": "some output",
// "key": "val",
// ...
// }
slog.Info("some message", "key", "val")
```
Use custom log levels if application requires more log levels
```go
import (
"log/slog"
log "github.com/fogfish/logger/v3"
)
slog.Log(context.Background(), log.EMERGENCY, "system emergency")
```
### Configuration
The default configuration is AWS CloudWatch friendly. It applies INFO level logging, disables timestamps and messages are emitted to standard error (`os.Stderr`). Use `logger.New` to create custom logger config.
```go
import (
"log/slog"
log "github.com/fogfish/logger/v3"
)
slog.SetDefault(
log.New(
log.WithWriter(),
log.WithLogLevel(),
log.WithLogLevelFromEnv(),
log.WithLogLevel7(),
log.WithLogLevelShorten(),
log.WithLogLevelForMod(),
log.WithLogLevelForModFromEnv(),
log.WithoutTimestamp(),
log.WithSourceFileName(),
log.WithSourceShorten(),
log.WithSource(),
),
)
```
#### Config Log Level from Env
Use environment variable `CONFIG_LOG_LEVEL` to change log level of the application at runtime
```bash
export CONFIG_LOGGER_LEVEL=WARN
```
### Enable DEBUG for single module
The logger allows to define a log level per module. It either explicitly defined via config option or environment variables. The logger uses each string as prefix to match it against source code path:
* `github.com/fogfish/logger/logger.go` defines log level for single file
* `github.com/fogfish/logger` defines log level for entire module
* `github.com/fogfish` defines log level for all modules by user
```go
import (
"log/slog"
log "github.com/fogfish/logger/v3"
)
slog.SetDefault(
log.New(
log.WithLogLevelForMod(map[string]slog.Level{
"github.com/fogfish/logger": log.INFO,
"github.com/you/application": log.DEBUG,
}),
),
)
```
Use environment variable `CONFIG_LOG_LEVEL_{LEVEL_NAME}`
```bash
export CONFIG_LOG_LEVEL_DEBUG=github.com/you/application:github.com/
export CONFIG_LOG_LEVEL_INFO=github.com/fogfish/logger
```
### AWS CloudWatch
The logger output events in the format compatible with AWS CloudWatch: each log message corresponds to single CloudWatch event. Therefore, it simplify logging in AWS Lambda functions. Use the logger together with CloudWatch Insight (e.g. utility [awslog](https://github.com/fogfish/awslog)) for the deep analysis. For example, search events with logs insight queries:
```
fields @timestamp, @message
| filter level = "INFO" and foo = "bar"
| sort @timestamp desc
| limit 20
```
## How To Contribute
The library is [MIT](LICENSE) licensed and accepts contributions via GitHub pull requests:
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
The build and testing process requires [Go](https://golang.org) version 1.16 or later.
**build** and **test** library.
```bash
git clone https://github.com/fogfish/logger
cd logger
```
### commit message
The commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter [Contributing to a Project](http://git-scm.com/book/ch5-2.html) of Git book.
### bugs
If you experience any issues with the library, please let us know via [GitHub issues](https://github.com/fogfish/logger/issue). We appreciate detailed and accurate reports that help us to identity and replicate the issue.
## License
[](LICENSE)