logger

package module
v3.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2024 License: MIT Imports: 8 Imported by: 1

README

logger

logging config for Golang's slog


logger is a configuration for Golang 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.

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")

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.

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

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
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}

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) 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 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 version 1.16 or later.

build and test library.

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 of Git book.

bugs

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.

License

See LICENSE

Documentation

Overview

Package logger configures slog for AWS CloudWatch

Index

Constants

View Source
const (
	// EMERGENCY
	// system is unusable, panic execution of current routine/application,
	// it is notpossible to gracefully terminate it.
	EMERGENCY = slog.Level(100)

	// CRITICAL
	// system is failed, response actions must be taken immediately,
	// the application is not able to execute correctly but still
	// able to gracefully exit.
	CRITICAL = slog.Level(50)

	// ERROR
	// 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.
	ERROR = slog.LevelError

	// WARN
	// system is failed, unable to recover, degraded functionality.
	// The failure is ignored and application still capable to deliver
	// incomplete but correct results.
	WARN = slog.LevelWarn

	// NOTICE
	// system is failed, error is recovered, no impact
	NOTICE = slog.Level(2)

	// INFO
	// output informative status about system
	INFO = slog.LevelInfo

	// DEBUG
	// output debug status about system
	DEBUG = slog.LevelDebug
)

Variables

This section is empty.

Functions

func New added in v3.1.0

func New(opts ...Option) *slog.Logger

Create New Logger

func NewJSONHandler added in v3.1.0

func NewJSONHandler(opts ...Option) slog.Handler

Create's new handler

Types

type Attributes added in v3.1.0

type Attributes []func(groups []string, a slog.Attr) slog.Attr

combinator of attribute formatting

type Option

type Option func(*opts)

Config options for slog

func WithLogLevel

func WithLogLevel(level slog.Leveler) Option

Config Log Level, default INFO

func WithLogLevel7 added in v3.1.0

func WithLogLevel7() Option

WithLevel7 enables from DEBUG to EMERGENCY levels

func WithLogLevelForMod added in v3.1.0

func WithLogLevelForMod(mods map[string]slog.Level) Option

Config Log Levels per module

func WithLogLevelForModFromEnv added in v3.1.0

func WithLogLevelForModFromEnv() Option

Config Log Levels per module from env variables CONFIG_LOG_LEVEL_{NAME}

CONFIG_LOG_LEVEL_DEBUG=github.com/fogfish/logger/*:github.com/your/app

func WithLogLevelFromEnv

func WithLogLevelFromEnv() Option

Config Log Level from env CONFIG_LOG_LEVEL, default INFO

func WithLogLevelShorten added in v3.1.0

func WithLogLevelShorten() Option

Config Log Level to be 3 letters only

func WithSource added in v3.1.0

func WithSource() Option

Enable logging of source file

func WithSourceFileName added in v3.1.0

func WithSourceFileName() Option

Logs file name of the source file

func WithSourceShorten added in v3.1.0

func WithSourceShorten() Option

Shorten Source file to letters only

func WithWriter

func WithWriter(w io.Writer) Option

Config Log writer, default os.Stdout

func WithoutTimestamp added in v3.1.0

func WithoutTimestamp() Option

Exclude timestamp, required by CloudWatch

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL