alog

README

common.queueb.org/slog
======================

.. contents::
  :local:
  :depth: 2

An extension for Go's standard structured logging package, ``log/slog``.

The package provides additional functionality for building and configuring structured 
logging while remaining compatible with the standard ``log/slog`` API.

It's still in development and used for internal queueb projects.

Installation
------------

Install the package with:

.. code-block:: console

   go get common.queueb.org/slog

Usage
-----

Import the package:

.. code-block:: go

   import "common.queueb.org/slog"

The API is built on top of the standard ``log/slog`` package and is intended 
for applications and libraries that need additional logging functionality.

Purpose
-------

This package is part of the QueueB collection of common Go libraries and provides reusable functionality related to structured logging.

The primary goal is to extend ``log/slog`` without introducing a separate logging system 
or requiring consumers to adopt a non-standard logging API.

Development
-----------

Documentation
~~~~~~~~~~~~~
Documentation is in development process. Sooner or later it would be available on 
Go Package Documentation: https://pkg.go.dev/common.queueb.org/slog

Source code: https://github.com/queueb-org/common-slog 

Testing
~~~~~~~

.. code-block:: bash

  $ go test -coverprofile=.coverage ./... && go tool cover -func=.coverage

License
-------

See the ``LICENSE`` file in the repository.

Documentation

Overview

Package alog represents application level logger, it's based on the structured log package provided within the standard library called slog.

Shortcut agreements:

• "a" is for slog.Attr (attribute)
• "v" is for slog.Value (value)

Index

• Constants
• Variables
• func Debug(msg string, args ...any)
• func DefaultReplaceAttr(groups []string, a slog.Attr) slog.Attr
• func Emergency(msg string, args ...any)
• func Env(envPrefixes ...string) func(string) string
• func Error(msg string, args ...any)
• func Info(msg string, args ...any)
• func Log(ctx context.Context, level slog.Level, msg string, args ...any)
• func LogLevelString(level slog.Level) string
• func NewContext(ctx context.Context, logger *Logger) context.Context
• func NewContextWithCancel(ctx context.Context, logger *Logger) (context.Context, context.CancelFunc)
• func Notice(msg string, args ...any)
• func ParseSilent() bool
• func ParseVerbosity() (level slog.Level)
• func ParseVerbosityInt() (verbosity int)
• func RemoveTime(groups []string, a slog.Attr) slog.Attr
• func ReplaceDefault(logger *Logger)
• func SetDefault(logger *Logger)
• func SetEnv(envPrefixes ...string)
• func Trace(msg string, args ...any)
• func Warning(msg string, args ...any)
• type Logger
  • func Default() *Logger
  • func FromContext(ctx context.Context) *Logger
  • func New(handler slog.Handler) *Logger
  • func (l *Logger) Notice(msg string, args ...any)
  • func (l *Logger) Trace(msg string, args ...any)
  • func (l *Logger) With(attrs ...any) *Logger
  • func (l *Logger) WithGroup(name string) *Logger
• type Sensitive
  • func (v Sensitive) LogValue() slog.Value

Constants

const (
	// LevelTrace is tracing level keeps debug-related information, usefull
	// to trace system behavior step by step.
	LevelTrace = slog.Level(-8)
	// LevelDebug is debugging level. At debugging level there might be
	// additional information about how application serves its actions.
	// Debug could be used to inspect how data is processed.
	// The difference between trace and debug is that debug should not consume
	// to chunky data to print it.
	LevelDebug = slog.LevelDebug
	// LevelInfo standard information level everything which is useful for
	// operation specialists.
	LevelInfo = slog.LevelInfo
	// LevelNotice stands for "enhanced" information, i.e. emphasized information which
	// might be helpful to inspect (but it's still ok). The difference between
	// warning and info is that knowledge does not require user actions (i.e. nothing is broken),
	// but it might be important to inform user with disabled info level.
	// The level could be treated as notification level.
	LevelNotice = slog.Level(2)
	// LevelWarning stands for warnings, warnings might expose information about
	// possible issues during running application, however, the app in the case
	// of such issues still available to maintain properly.
	LevelWarning = slog.LevelWarn
	// LevelError stands for errors occurred while application was/is running.
	// It means something should be done outside the application scope to make it fixed/start
	// running properly.
	LevelError = slog.LevelError
	// LevelEmergency stands for extraordinary errors.
	LevelEmergency = slog.Level(12)
)

Logging Levels.

const (
	// EnvVerbosity is an environment variable (suffix) to use for manipulating with verbosity.
	// verbosity takes integer values like 0, 1, 2, etc.
	// It can be used with ${APP}_VERBOSITY where ${APP} is set over [Env], [SetEnv] helpers.
	EnvVerbosity = "VERBOSITY"
	// EnvSilent is an environment variable to use for manipulating with logger in general to
	// switch it off.
	EnvSilent = "SILENT"

	// FlagSilent is a full argument flag for silent option.
	FlagSilent = "--silent"
)

Env settings for the package.

const (
	// EnvSensitiveDisable keeps environment variable that
	// disables sensitive formatter. Use it only for debug
	// purposes and never set it on.
	EnvSensitiveDisable = "DISABLE_SENSITIVE_REDUCTION"
)

Variables

var (
	// DefaultHandlerOptions is used for new logger instances created objects.
	DefaultHandlerOptions = &slog.HandlerOptions{
		AddSource: false,
		Level:     LevelWarning,

		ReplaceAttr: DefaultReplaceAttr,
	}
)

Functions

func Debug

func Debug(msg string, args ...any)

Debug logs a debug info over Default logger instance.

func DefaultReplaceAttr

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

DefaultReplaceAttr serves to expose additional log levels.

func Emergency

func Emergency(msg string, args ...any)

Emergency logs an emergency over Default logger instance.

func Env

func Env(envPrefixes ...string) func(string) string

Env provides a helper to join environment variable prefixes together and return one argument function as a helper.

func Error

func Error(msg string, args ...any)

Error logs an error over Default logger instance.

func Info

func Info(msg string, args ...any)

Info logs an info over Default logger instance.

func Log

func Log(ctx context.Context, level slog.Level, msg string, args ...any)

Log invokes default logger log function

func LogLevelString

func LogLevelString(level slog.Level) string

LogLevelString shows log level in a human-readable format based on level.

func NewContext

func NewContext(ctx context.Context, logger *Logger) context.Context

NewContext creates a context and set logger for its further use.

func NewContextWithCancel

func NewContextWithCancel(ctx context.Context, logger *Logger) (context.Context, context.CancelFunc)

NewContextWithCancel creates a context with set logger and cancel function.

func Notice

func Notice(msg string, args ...any)

Notice logs a notice over Default logger instance.

func ParseSilent

func ParseSilent() bool

ParseSilent identifies if silent is set over cli arguments or environment variables.

func ParseVerbosity

func ParseVerbosity() (level slog.Level)

ParseVerbosity parses verbosity level for the application

Emergency: -2
Error: -1
Warning: 0
Notice: 1
Info: 2
Debug: 3
Trace: 4

func ParseVerbosityInt

func ParseVerbosityInt() (verbosity int)

ParseVerbosityInt returns verbosity in [int] form.

func RemoveTime

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

RemoveTime removes the top-level time attribute. It is intended to be used as a ReplaceAttr function, to make example output deterministic.

func ReplaceDefault

func ReplaceDefault(logger *Logger)

ReplaceDefault replaces default logger link.

func SetDefault

func SetDefault(logger *Logger)

SetDefault sets given logger as a default module logger.

func SetEnv

func SetEnv(envPrefixes ...string)

SetEnv sets environment variables prefix (works on a global level, so you can set it once for whole application). Example:

SetEnv("MY", "APP") // results as MY_APP_<ARGUMENT>

func Trace

func Trace(msg string, args ...any)

Trace logs a tracing info over Default logger instance.

func Warning

func Warning(msg string, args ...any)

Warning logs a warning over Default logger instance.

Types

type Logger

type Logger struct {
	*slog.Logger
}

Logger extends slog.Logger with additional helpers.

func Default

func Default() *Logger

Default returns default module logger.

func FromContext

func FromContext(ctx context.Context) *Logger

FromContext extracts logger instance from context, if there's no pre-set logger => default will be used.

func New

func New(handler slog.Handler) *Logger

New creates a logger

func (*Logger) Notice

func (l *Logger) Notice(msg string, args ...any)

Notice implements notice helper

func (*Logger) Trace

func (l *Logger) Trace(msg string, args ...any)

Trace implements tracing helper

func (*Logger) With

func (l *Logger) With(attrs ...any) *Logger

With sets additional attributes.

func (*Logger) WithGroup

func (l *Logger) WithGroup(name string) *Logger

WithGroup sets group for a logger.

type Sensitive

type Sensitive string

Sensitive is a secret value that should not be exposed in a logger.

func (Sensitive) LogValue

func (v Sensitive) LogValue() slog.Value

LogValue implements slog.LogValuer. It avoids revealing the token.