log

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Apr 3, 2026 License: MIT Imports: 12 Imported by: 0

README

Logging Configuration

This package provides a flexible logging configuration system built on top of Uber's zap logging library.

Configuration Options

The logging can be configured through flags or environment variables. Here are all available options:

Basic Configuration
Log Level

Controls the minimum logging level.

  • Flag: --log-level
  • Environment: LOG_LEVEL
  • Values: debug, info, warn, error
  • Default: info
Log Format

Controls the output format of the logs.

  • Flag: --log-format
  • Environment: LOG_FORMAT
  • Values: text, json
  • Default: text
Stack Traces

Controls whether stack traces are included for errors.

  • Flag: --log-enable-stacktrace
  • Environment: LOG_ENABLE_STACKTRACE
  • Values: true, false
  • Default: false
Caller Information

Controls whether to include the caller (file and line) in log entries.

  • Flag: --log-enable-caller
  • Environment: LOG_ENABLE_CALLER
  • Values: true, false
  • Default: false
Output Configuration
Output Paths

Controls where logs are written.

  • Flag: --log-output-paths
  • Environment: LOG_OUTPUT_PATHS
  • Values: Array of paths (e.g., stdout, stderr, /var/log/app.log)
  • Default: stderr
Error Output Paths

Controls where error logs are written.

  • Flag: --log-error-output-paths
  • Environment: LOG_ERROR_OUTPUT_PATHS
  • Values: Array of paths (e.g., stdout, stderr, /var/log/app.error.log)
  • Default: stderr
Sampling Configuration

Controls log sampling to prevent overwhelming output in high-throughput scenarios.

Initial Sample

Number of entries with the same message and level to process before sampling begins.

  • Flag: --log-sampling-initial
  • Environment: LOG_SAMPLING_INITIAL
  • Values: Any positive integer
  • Default: 100
Thereafter Sample

After initial sample, log every Nth message.

  • Flag: --log-sampling-thereafter
  • Environment: LOG_SAMPLING_THEREAFTER
  • Values: Any positive integer
  • Default: 100

Advanced Configuration

Key Names

Configure the keys used in structured logging:

  • Message Key

    • Flag: --log-encoder-message-key
    • Environment: LOG_ENCODER_MESSAGE_KEY
    • Default: msg

  • Level Key

    • Flag: --log-encoder-level-key
    • Environment: LOG_ENCODER_LEVEL_KEY
    • Default: level

  • Time Key

    • Flag: --log-encoder-time-key
    • Environment: LOG_ENCODER_TIME_KEY
    • Default: ts

  • Name Key

    • Flag: --log-encoder-name-key
    • Environment: LOG_ENCODER_NAME_KEY
    • Default: logger

  • Caller Key

    • Flag: --log-encoder-caller-key
    • Environment: LOG_ENCODER_CALLER_KEY
    • Default: caller

  • Function Key

    • Flag: --log-encoder-function-key
    • Environment: LOG_ENCODER_FUNCTION_KEY
    • Default: `` (empty)

  • Stacktrace Key

    • Flag: --log-encoder-stacktrace-key
    • Environment: LOG_ENCODER_STACKTRACE_KEY
    • Default: stacktrace
Encoder Configuration
Level Encoder

Controls how the log level is formatted.

  • Flag: --log-encoder-level-encoder
  • Environment: LOG_ENCODER_LEVEL_ENCODER
  • Values:
    • capital - "INFO", "ERROR"
    • capitalColor - "INFO" (with color)
    • color - "info" (with color)
    • lowercase - "info", "error"
  • Default: capitalColor
Time Encoder

Controls how timestamps are formatted.

  • Flag: --log-encoder-time-encoder
  • Environment: LOG_ENCODER_TIME_ENCODER
  • Values:
    • rfc3339nano - RFC3339 with nanoseconds
    • rfc3339 - RFC3339
    • iso8601 - ISO8601
    • millis - Milliseconds since epoch
    • nanos - Nanoseconds since epoch
    • time - Custom format "2006-01-02T15:04:05.000Z07:00"
  • Default: time
Duration Encoder

Controls how durations are formatted.

  • Flag: --log-encoder-duration-encoder
  • Environment: LOG_ENCODER_DURATION_ENCODER
  • Values:
    • string - Human-readable duration (e.g. "1s")
    • nanos - Nanoseconds as integer
    • ms - Milliseconds as integer
    • s - Seconds as float
  • Default: s
Caller Encoder

Controls how caller information is formatted.

  • Flag: --log-encoder-caller-encoder
  • Environment: LOG_ENCODER_CALLER_ENCODER
  • Values:
    • full - Full file path
    • short - Package name and file
  • Default: short
Name Encoder

Controls how logger names are formatted.

  • Flag: --log-encoder-name-encoder
  • Environment: LOG_ENCODER_NAME_ENCODER
  • Values:
    • full - Full logger name
  • Default: full
Output Formatting
Line Ending

  • Skip Line Ending

    • Flag: --log-encoder-skip-line-ending
    • Environment: LOG_ENCODER_SKIP_LINE_ENDING
    • Values: true, false
    • Default: false

  • Line Ending

    • Flag: --log-encoder-line-ending
    • Environment: LOG_ENCODER_LINE_ENDING
    • Default: \n
Console Separator

Controls the separator used in console output format.

  • Flag: --log-encoder-console-separator
  • Environment: LOG_ENCODER_CONSOLE_SEPARATOR
  • Default: \t (tab)

Example Usage

Using flags:

./myapp --log-level debug --log-format json --log-enable-stacktrace true --log-enable-caller true

Using environment variables:

LOG_LEVEL=debug LOG_FORMAT=json LOG_ENABLE_STACKTRACE=true LOG_ENABLE_CALLER=true ./myapp

Advanced configuration example:

./myapp \
  --log-level debug \
  --log-format json \
  --log-encoder-time-encoder rfc3339nano \
  --log-encoder-level-encoder capitalColor \
  --log-encoder-caller-encoder full \
  --log-encoder-console-separator "  " \
  --log-sampling-initial 100 \
  --log-sampling-thereafter 100 \
  --log-output-paths stdout,/var/log/app.log \
  --log-error-output-paths stderr,/var/log/app.error.log

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddFlags 

func AddFlags(v *viper.Viper, f *pflag.FlagSet, hooks ...config.EncodeHookFunc) error

AddFlags adds flags to the given viper and pflag.FlagSet. Sets - all viper keys with "log." prefix - all environment variables with "LOG_" prefix - all flags with "log-" prefix

func LoggerFromContext 

func LoggerFromContext(ctx context.Context) *zap.Logger

LoggerFromContext returns a logger from the given context with the default namespace tags attached to it

func LoggerWithFieldsFromContext 

func LoggerWithFieldsFromContext(ctx context.Context) *zap.Logger

LoggerWithFieldsFromContext returns a logger from the given context with the default namespace tags attached to it

func LoggerWithFieldsFromNamespaceContext 

func LoggerWithFieldsFromNamespaceContext(ctx context.Context, namespaces ...string) *zap.Logger

LoggerWithFieldsFromNamespaceContext returns a logger from the given context. It loads the tags from the provided tags namespace and adds them to the logger.

func TagsToFields 

func TagsToFields(tags []*tag.Tag) []zap.Field

TagsToFields converts a slice of tags to zap fields

func WithLogger 

func WithLogger(ctx context.Context, logger *zap.Logger) context.Context

WithLogger returns a new context with the given logger attached to it

Types

type CallerEncoder 

type CallerEncoder int
const (
	CallerEncoderFull CallerEncoder = iota
	CallerEncoderShort
)

func ParseCallerEncoder 

func ParseCallerEncoder(encoder string) (CallerEncoder, error)

func (CallerEncoder) MarshalJSON added in v0.9.1 

func (c CallerEncoder) MarshalJSON() ([]byte, error)

func (CallerEncoder) String 

func (c CallerEncoder) String() string

type Config 

type Config struct {
	Format           *Format         `key:"format,omitempty" desc:"Log format"`
	Level            *Level          `key:"level,omitempty" desc:"Minimum enabled logging level"`
	EnableStacktrace *bool           `` /* 126-byte string literal not displayed */
	EnableCaller     *bool           `key:"enableCaller,omitempty" env:"ENABLE_CALLER" flag:"enable-caller" desc:"Enable caller"`
	Encoder          *EncoderConfig  `key:"encoding,omitempty" flag:"encoding" env:"ENCODING" desc:"Encoding: "`
	Sampling         *SamplingConfig `key:"sampling,omitempty" desc:"Sampling: "`
	OutputPaths      *[]*string      `key:"outputPaths,omitempty" env:"OUTPUT_PATHS" flag:"output" desc:"List of URLs or file paths to write logging output to"`
	ErrorOutputPaths *[]*string      `` /* 130-byte string literal not displayed */
}

Config is the configuration to create a zap.Config.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a default Config.

func (*Config) Env 

func (cfg *Config) Env(hooks ...config.EncodeHookFunc) (map[string]string, error)

Env returns the environment variables for the given Config. All environment variables are prefixed with "LOG_".

func (*Config) MarshalJSON added in v0.9.1 

func (cfg *Config) MarshalJSON() ([]byte, error)

func (*Config) Unmarshal 

func (cfg *Config) Unmarshal(v *viper.Viper) error

Unmarshal unmarshals the given viper into the Config. Assumes - all viper keys are prefixed with "log." - all environment variables are prefixed with "LOG_".

func (*Config) ZapConfig 

func (cfg *Config) ZapConfig() *zap.Config

type DurationEncoder 

type DurationEncoder int
const (
	DurationEncoderString DurationEncoder = iota
	DurationEncoderNanos
	DurationEncoderMillis
	DurationEncoderSeconds
)

func ParseDurationEncoder 

func ParseDurationEncoder(encoder string) (DurationEncoder, error)

func (DurationEncoder) MarshalJSON added in v0.9.1 

func (d DurationEncoder) MarshalJSON() ([]byte, error)

func (DurationEncoder) String 

func (d DurationEncoder) String() string

type EncoderConfig 

type EncoderConfig struct {
	MessageKey       *string          `` /* 129-byte string literal not displayed */
	LevelKey         *string          `key:"levelKey,omitempty" env:"LEVEL_KEY" flag:"level-key" desc:"Key for the log level (if empty, the level is omitted)"`
	TimeKey          *string          `key:"timeKey,omitempty" env:"TIME_KEY" flag:"time-key" desc:"Key for the log timestamp (if empty, the timestamp is omitted)"`
	NameKey          *string          `` /* 128-byte string literal not displayed */
	CallerKey        *string          `key:"callerKey,omitempty" env:"CALLER_KEY" flag:"caller-key" desc:"Key for the log caller (if empty, the caller is omitted)"`
	FunctionKey      *string          `` /* 134-byte string literal not displayed */
	StacktraceKey    *string          `` /* 144-byte string literal not displayed */
	SkipLineEnding   *bool            `key:"skipLineEnding,omitempty" env:"SKIP_LINE_ENDING" flag:"skip-line-ending" desc:"Skip the line ending"`
	LineEnding       *string          `key:"lineEnding,omitempty" env:"LINE_ENDING" flag:"line-ending" desc:"Line ending"`
	LevelEncoder     *LevelEncoder    `` /* 174-byte string literal not displayed */
	TimeEncoder      *TimeEncoder     `` /* 190-byte string literal not displayed */
	DurationEncoder  *DurationEncoder `` /* 167-byte string literal not displayed */
	CallerEncoder    *CallerEncoder   `` /* 146-byte string literal not displayed */
	NameEncoder      *NameEncoder     `` /* 145-byte string literal not displayed */
	ConsoleSeparator *string          `` /* 132-byte string literal not displayed */
}

func (*EncoderConfig) EncoderConfig 

func (cfg *EncoderConfig) EncoderConfig() *zapcore.EncoderConfig

func (*EncoderConfig) MarshalJSON added in v0.9.1 

func (cfg *EncoderConfig) MarshalJSON() ([]byte, error)

type Format 

type Format int
const (
	TextFormat Format = iota
	JSONFormat
)

func ParseFormat 

func ParseFormat(format string) (Format, error)

func (Format) MarshalJSON added in v0.9.1 

func (f Format) MarshalJSON() ([]byte, error)

func (Format) String 

func (f Format) String() string

type Level 

type Level int
const (
	DebugLevel Level = iota
	InfoLevel
	WarnLevel
	ErrorLevel
)

func ParseLevel 

func ParseLevel(level string) (Level, error)

func (Level) MarshalJSON added in v0.9.1 

func (l Level) MarshalJSON() ([]byte, error)

func (Level) String 

func (l Level) String() string

type LevelEncoder 

type LevelEncoder int
const (
	LevelEncoderCapital LevelEncoder = iota
	LevelEncoderCapitalColor
	LevelEncoderColor
	LevelEncoderLowercase
)

func ParseLevelEncoder 

func ParseLevelEncoder(encoder string) (LevelEncoder, error)

func (LevelEncoder) MarshalJSON added in v0.9.1 

func (l LevelEncoder) MarshalJSON() ([]byte, error)

func (LevelEncoder) String 

func (l LevelEncoder) String() string

type NameEncoder 

type NameEncoder int
const (
	NameEncoderFull NameEncoder = iota
	NameEncoderShort
)

func ParseNameEncoder 

func ParseNameEncoder(encoder string) (NameEncoder, error)

func (NameEncoder) MarshalJSON added in v0.9.1 

func (n NameEncoder) MarshalJSON() ([]byte, error)

func (NameEncoder) String 

func (n NameEncoder) String() string

type SamplingConfig 

type SamplingConfig struct {
	Initial    *int `key:"initial,omitempty" desc:"Number of log entries with the same level and message to log before dropping entries"`
	Thereafter *int `key:"thereafter,omitempty" desc:"After the initial number of entries, every Mth entry is logged and the rest are dropped"`
}

func (*SamplingConfig) MarshalJSON added in v0.9.1 

func (cfg *SamplingConfig) MarshalJSON() ([]byte, error)

type TimeEncoder 

type TimeEncoder int
const (
	TimeEncoderRFC3339Nano TimeEncoder = iota
	TimeEncoderRFC3339
	TimeEncoderISO8601
	TimeEncoderMillis
	TimeEncoderNanos
	TimeEncoderTime
)

func ParseTimeEncoder 

func ParseTimeEncoder(encoder string) (TimeEncoder, error)

func (TimeEncoder) MarshalJSON added in v0.9.1 

func (t TimeEncoder) MarshalJSON() ([]byte, error)

func (TimeEncoder) String 

func (t TimeEncoder) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.