c4hgol

README

c4hgol

import "git.fractalqb.de/fractalqb/c4hgol"

---

Configuration for Heterogeneous Go Loggers

Though Go has a logging package in its standard library this package is rather basic. IMHO this is the reason why there are several additional and different logging libraries in the Go community which lead to some irritation when one wants to write an application that ends up with having several different logging frameworks included due to package dependencies.

This package does not address the desire to have one unified logger or at least a unified logging interface. – Let the packages choose their loggers… for good or for bad. However, what I want to be able to do is configure all those loggers in my application in a unified way! At least configure some common things that one often wants to configure:

• Switching loggers for some “topics” on and off
• Setting the log level of loggers
• Set a writer as the target for the logging messages
• (to come: log format?)

Note that the first bullet in the list gives the hint that loggers shall be grouped into topics so that configuration becomes simpler.

Log Packages Architecture Proposition

Make a virtue of necessity…

Theoretical Approach

First of all one has to question why it could come to the situation that a single executable includes different logging libraries! If each component (library), an executable is made of, returns detailed information about the outcome of each of its offered services (functions/methods) the executable can decide if and how to log those outcomes.—No need for a component to do logging at all, i.e. only the executable uses logging and therefore can arrange to use one logging library.

In theory this could be done for exceptional situations, aka errors. Here one could start to collect context information at the point of failure. This information then propagates back to the executable while being enriched with relevant context information. Again, it would be up to the executable to decide what to do with this.

For “small” components and when executables have a rather shallow dependency graph this approach does not only work well, it is also a desirable approach. – It keeps things simple!

Facing the Real World…

…at least when things become more and more complex. In reality we often see requirements that break the Theoretical Approach:

• In practice error/exception handling is rarely perfect and most often only comes with a text message. This makes reasonable decisions difficult for executables.

• As soon as one also wants information about the happy case details from a deeply “buried” component it gets difficult, if not impossible, for top-level executable's code to get that.

For short: One has to expect that sufficiently sophisticated components come with their own logging included.

Would that be a problem? IMHO not, as long as you have some means to configure the loggers to your need. I.e. make c4hgol a concept! This would address the need of application developers and gives reasonable choices to component developers:

1. Component developers can chose their logging API

2. Logging calls can be static calls, i.e. no dynamic dispatching through interfaces

Used by

• qbsllm – combines sllm structured logging and c4hgol into one logging library.

Documentation

Overview

Though Go has a logging package in its standard library this package is rather basic. IMHO this is the reason why there are several additional and different logging libraries in the Go community which lead to some irritation when one wants to write an application that ends up with having several different logging frameworks included due to package dependencies.

This package does not address the desire to have one unified logger or at least a unified logging interface. – Let the packages choose their loggers… for good or for bad. However, what I want to be able to do is configure all those loggers in my application in a unified way! At least configure some common things that one often wants to configure:

- Switching loggers for some “topics” on and off

- Setting the log level of loggers

- (may be other things to come in the future)

Note that the first bullet in the list gives the hint that loggers shall be hierarchically grouped so that configuration becomes simpler.

Index

• func Configure(cfg Config, desc string, strict bool) error
• func FeatureType(feature any) string
• func FlagDoc() string
• func Visit(start Config, do func(c Config, path string) error) error
• type Config
• type Enable
• type Group
  • func MustNewGroup(name string, members ...Config) *Group
  • func MustNewLogGroup(cfg Config, name string, members ...Config) *Group
  • func NewGroup(name string, members ...Config) (*Group, error)
  • func NewLogGroup(cfg Config, name string, members ...Config) (*Group, error)
  • func (g *Group) Set(feature any) (err error)
• type Level
  • func (l Level) String() string
• type LevelMap
  • func MustNewLevelMap(pairs ...any) LevelMap
  • func NewLevelMap(pairs ...any) (LevelMap, error)
  • func (m LevelMap) Map(a int64) int64
  • func (m LevelMap) Revert(b int64) int64
• type Named
  • func MustNewNamed(cfg Config, name string) *Named
  • func NewNamed(cfg Config, name string) (*Named, error)
  • func (n *Named) Features() []any
  • func (n *Named) Get(zero any) (value any, err error)
  • func (n *Named) Name() string
  • func (n *Named) Path() string
  • func (n *Named) Set(feature any) error
• type Output
  • func (o Output) String() string
• type Source
  • func (l Source) String() string
• type Unsupported
  • func (u Unsupported) Error() string
  • func (u Unsupported) Is(err error) bool

Examples

• FeatureType

Functions

func Configure

func Configure(cfg Config, desc string, strict bool) error

TODO enable / disable

func FeatureType

func FeatureType(feature any) string

Example

fmt.Println(FeatureType(Enable(false)))
fmt.Println(FeatureType(InfoLevel))
fmt.Println(FeatureType(Output{os.Stderr}))
fmt.Println(FeatureType(SrcFile))

Output:

git.fractalqb.de/fractalqb/c4hgol.Enable
git.fractalqb.de/fractalqb/c4hgol.Level
git.fractalqb.de/fractalqb/c4hgol.Output
git.fractalqb.de/fractalqb/c4hgol.Source

func FlagDoc

func FlagDoc() string

func Visit

func Visit(start Config, do func(c Config, path string) error) error

Types

type Config

type Config interface {
	Set(feature any) error
	Get(zero any) (value any, err error)
	Features() []any
}

type Enable

type Enable bool

type Group

type Group struct {
	Named
	// contains filtered or unexported fields
}

func MustNewGroup

func MustNewGroup(name string, members ...Config) *Group

func MustNewLogGroup

func MustNewLogGroup(cfg Config, name string, members ...Config) *Group

func NewGroup

func NewGroup(name string, members ...Config) (*Group, error)

func NewLogGroup

func NewLogGroup(cfg Config, name string, members ...Config) (*Group, error)

func (*Group) Set

func (g *Group) Set(feature any) (err error)

type Level

type Level int

const (
	TraceLevel Level = -100
	DebugLevel Level = -50
	InfoLevel  Level = 0
	WarnLevel  Level = 50
	ErrorLevel Level = 100

	DefaultLevel = InfoLevel
)

func (Level) String

func (l Level) String() string

type LevelMap

type LevelMap struct {
	// contains filtered or unexported fields
}

func MustNewLevelMap

func MustNewLevelMap(pairs ...any) LevelMap

func NewLevelMap

func NewLevelMap(pairs ...any) (LevelMap, error)

func (LevelMap) Map

func (m LevelMap) Map(a int64) int64

func (LevelMap) Revert

func (m LevelMap) Revert(b int64) int64

type Named

type Named struct {
	// contains filtered or unexported fields
}

func MustNewNamed

func MustNewNamed(cfg Config, name string) *Named

func NewNamed

func NewNamed(cfg Config, name string) (*Named, error)

func (*Named) Features

func (n *Named) Features() []any

func (*Named) Get

func (n *Named) Get(zero any) (value any, err error)

func (*Named) Name

func (n *Named) Name() string

func (*Named) Path

func (n *Named) Path() string

func (*Named) Set

func (n *Named) Set(feature any) error

type Output

type Output struct {
	io.Writer
}

func (Output) String

func (o Output) String() string

type Source

type Source int

const (
	SrcOff Source = iota
	SrcFile
	SrcPath
	SrcStack
)

func (Source) String

func (l Source) String() string

type Unsupported

type Unsupported struct {
	Feature any
}

func (Unsupported) Error

func (u Unsupported) Error() string

func (Unsupported) Is

func (u Unsupported) Is(err error) bool