logger is a configuration for Golang slog developed for easy to use within serverless applications (e.g. logging to AWS CloudWatch).
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:
EMERGENCY
, EMR
: system is unusable, panic execution of current routine or application, it is not possible to gracefully terminate it.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.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.WARN
, WRN
: system is failed, unable to recover, degraded functionality. The failure is ignored and application still capable to deliver incomplete but correct results.NOTICE
, NTC
: system is failed, error is recovered, no impact.INFO
, INF
: output informative status about system.DEBUG
, DEB
: output debug status about system.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.
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
import (
"log/slog"
log "github.com/fogfish/logger/v3"
)
slog.Log(context.Background(), log.EMERGENCY, "system emergency")
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.
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(),
),
)
Use environment variable CONFIG_LOG_LEVEL
to change log level of the application at runtime
export CONFIG_LOGGER_LEVEL=WARN
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 filegithub.com/fogfish/logger
defines log level for entire modulegithub.com/fogfish
defines log level for all modules by userimport (
"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}
export CONFIG_LOG_LEVEL_DEBUG=github.com/you/application:github.com/
export CONFIG_LOG_LEVEL_INFO=github.com/fogfish/logger
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) 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
The library is MIT licensed and accepts contributions via GitHub pull requests:
git checkout -b my-new-feature
)git commit -am 'Added some feature'
)git push origin my-new-feature
)The build and testing process requires Go version 1.16 or later.
build and test library.
git clone https://github.com/fogfish/logger
cd logger
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 of Git book.
If you experience any issues with the library, please let us know via GitHub issues. We appreciate detailed and accurate reports that help us to identity and replicate the issue.