log

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: May 9, 2026 License: BSD-3-Clause Imports: 14 Imported by: 1

README

Log

Go Report Card GoDoc Go Version

Package log provides a flexible logging library for Go applications. It sends log messages simultaneously to stdout, file, and Elasticsearch — with structured fields, level filtering, and graceful shutdown.

Compatible with the standard log package — calls like log.Println() are intercepted and routed through the same pipeline.

Features

  • Multi-output: stdout (console), file (disk), Elasticsearch (JSON)
  • Standard log compatibility: log.SetOutput() interception via customWriter
  • Log levels: DEBUG, INFO, WARN, ERROR, NONE
  • Structured fields: last argument map[string]any auto-extracted as Fields
  • Level filtering: suppress specific levels via Config.FilterLevels
  • Elasticsearch: asynchronous bulk sending with retry and overflow buffer
  • File logger: write to disk with configurable path
  • JSON output: LogEntry.Json() for ES-compatible format
  • Graceful shutdown: Close() waits for all loggers via sync.WaitGroup
  • Type-safe helpers: Debug, Info, Warn, Error + string variants Sdebug, Sinfo, etc.

Installation

go get github.com/kirill-scherba/log

Quick Start

package main

import (
    "log"
    "github.com/kirill-scherba/log"
)

func main() {
    // Initialize with stdout only
    log.Init(&log.Config{
        AppShort: "myapp",
        AppType:  "DEV",
        UseStdout: true,
    })
    defer log.Close()

    // Use compatible standard log calls
    log.Println("Hello from standard log")

    // Use typed helpers with levels
    log.Debug("debug message")
    log.Info("info message")
    log.Warn("warn message")
    log.Error("error message")

    // With structured fields (auto-detected map[string]any)
    log.Info("user action", map[string]any{"user": "john", "action": "login"})

    // Formatted output with fields
    log.Infof("processed %d records", 42, map[string]any{"batch": "nightly"})
}

Output:

2025/10/19 10:28:50.567024 [DEBUG] Hello from standard log
2025/10/19 10:28:50.567025 [DEBUG] debug message
2025/10/19 10:28:50.567026 [INFO]  info message
2025/10/19 10:28:50.567027 [WARN]  warn message
2025/10/19 10:28:50.567028 [ERROR] error message
2025/10/19 10:28:50.567029 [INFO]  user action, fields: map[user:john action:login]

Configuration

Config Field Type Description
AppShort string Short application name
AppType string Application type: DEV, PROD, TEST
UseStdout bool Write to stdout (default: true on Init)
EsConfig *EsConfig Elasticsearch config (nil = disabled)
FileConfig *FileConfig File logger config (nil = disabled)
FilterLevels []LogLevel Levels to suppress
CustomLogers []*log.Logger Additional loggers to intercept
Elasticsearch
log.Init(&log.Config{
    AppShort: "myapp",
    AppType:  "PROD",
    UseStdout: true,
    EsConfig: &log.EsConfig{
        URL:           "http://localhost:9200",
        IndexName:     "myapp-logs",
        EntryChanelSize: 100,
    },
})
File
log.Init(&log.Config{
    AppShort: "myapp",
    AppType:  "PROD",
    UseStdout: true,
    FileConfig: &log.FileConfig{
        FilePath: "/var/log/myapp/app.log",
    },
})
Level filtering (suppress DEBUG in production)
log.Init(&log.Config{
    AppShort:     "myapp",
    AppType:      "PROD",
    UseStdout:    true,
    FilterLevels: []log.LogLevel{log.LevelDebug},
})

API Reference

Initialization
Function Description
Init(config *Config) Initialize loggers and intercept standard log
Close() Flush and shut down all loggers
Output helpers (send to all active loggers)
Function Level Description
Debug(v ...any) DEBUG Log with debug level
Debugf(format, v ...any) DEBUG Formatted debug log
Info(v ...any) INFO Log with info level
Infof(format, v ...any) INFO Formatted info log
Warn(v ...any) WARN Log with warn level
Warnf(format, v ...any) WARN Formatted warn log
Error(v ...any) ERROR Log with error level
Errorf(format, v ...any) ERROR Formatted error log
Println(v ...any) default Debug-level log (standard compatibility)
Printf(format, v ...any) default Formatted debug log
Fatalln(v ...any) ERROR Error + os.Exit(1)
Fatalf(format, v ...any) ERROR Formatted error + os.Exit(1)
Fatal(v ...any) ERROR Error + os.Exit(1)
String helpers (return JSON string, do NOT send to outputs)
Function Level Description
Sdebug(v ...any) DEBUG Return debug JSON string
Sdebugf(format, v ...any) DEBUG Return formatted debug JSON string
Sinfo(v ...any) INFO Return info JSON string
Sinfof(format, v ...any) INFO Return formatted info JSON string
Swarn(v ...any) WARN Return warn JSON string
Swarnf(format, v ...any) WARN Return formatted warn JSON string
Serror(v ...any) ERROR Return error JSON string
Serrorf(format, v ...any) ERROR Return formatted error JSON string
Sentry(level, v ...any) any Return JSON string at specified level
Sentryf(level, format, v ...any) any Return formatted JSON string at specified level
Utility
Function Description
SetDefaultLevel(level) Set default level for standard log calls
SetOutput(w io.Writer) Redirect standard log output

Log Levels

Constant Value Description
LevelDebug DEBUG Detailed debug information
LevelInfo INFO Informational messages
LevelWarn WARN Warning messages
LevelError ERROR Error messages
LevelNone "" Silence all standard logs

How It Works

   log.Println() ──► customWriter ──► parse [LEVEL] ──► loggers.send()
                                                           ├── stdout
                                                           ├── file (async)
                                                           └── Elasticsearch (async, batch)

The customWriter implements io.Writer and is set via log.SetOutput(). It:

  1. Strips standard Go timestamp
  2. Parses log level from [LEVEL] prefix (falls back to LevelDefault)
  3. Sends the resulting LogEntry through the dispatch pipeline

License

BSD

Documentation

Overview

Package log contains log functions to send logs to stdout, files and Elasticsearch.

The log compatible with standard log package, f.e. log.Println are available.

The log messages sends to elasticsearch has json format with basic fields (timestamp, level, message) and additional fields in key-value format.

Index

Constants

This section is empty.

Variables

View Source 
var LevelDefault = LevelDebug

Default log level uset in standart log calls, f.e. log.Println

Functions

func Close added in v0.0.2 

func Close()

Close closes the Elasticsearch logger and the file logger. It is called once when the application exits. It stops the Elasticsearch logger and the file logger from writing log entries to Elasticsearch and/or to disk.

func Debug 

func Debug(v ...any)

Debug is a convenience function for creating log entries at the debug log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Debugf 

func Debugf(format string, v ...any)

Debugf is a convenience function for creating log entries at the debug log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

func Error 

func Error(v ...any)

Error is a convenience function for creating log entries at the error log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Errorf 

func Errorf(format string, v ...any)

Errorf is a convenience function for creating log entries at the error log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

func Fatal 

func Fatal(v ...any)

Fatal is a convenience function for creating log entries at the error log level and then exiting the program with a non-zero exit code.

It takes a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The first map in the list is used as the fields for the log entry.

The function calls Error with the given values and then exits the program with a non-zero exit code.

func Fatalf 

func Fatalf(format string, v ...any)

Fatalf is a convenience function for creating log entries at the error log level and then exiting the program with a non-zero exit code.

It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

The function calls Errorf with the given format string and values and then exits the program with a non-zero exit code.

func Fatalln 

func Fatalln(v ...any)

Fatalln is a convenience function for creating log entries at the error log level and then exiting the program with a non-zero exit code.

It takes a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The first map in the list is used as the fields for the log entry.

The function calls Fatal with the given values and then exits the program with a non-zero exit code.

func Info 

func Info(v ...any)

Info is a convenience function for creating log entries at the info log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Infof 

func Infof(format string, v ...any)

Infof is a convenience function for creating log entries at the info log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

func Init 

func Init(config *Config)

Init sets up the loggers and sets the output for the default application logger and for some additional loggers. It is called once when the application starts. apptype is the application type, which is used to prefix log messages. useStdout is a boolean that indicates whether to write log messages to stdout. esConfig is a pointer to an EsConfig struct, which holds information about how to send log entries to Elasticsearch. If esConfig is not nil, the loggers are set up to write log entries to Elasticsearch. The Elasticsearch logger config is set to the provided esConfig. The Elasticsearch logger config is set to the provided esConfig. If the MaxOverflowBuffer is 0, it is set to 2x the entryChannel size, or a fixed number if entryChannel size is 0. If the MaxRetryBuffer is 0, it is set to 100 batches. The Elasticsearch logger config is set to the provided esConfig. The Elasticsearch logger config is set to the provided esConfig. The loggers are then started and the output for the default application logger and for some additional loggers is set to a customWriter, which writes log entries to stdout and/or to Elasticsearch. Finally, a message is printed to indicate that the loggers have been initialized.

func PrintLevel 

func PrintLevel(level LogLevel, v ...any)

PrintLevel is a convenience function for creating log entries at the given log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func PrintLevelf 

func PrintLevelf(level LogLevel, format string, v ...any)

PrintLevelf is a convenience function for creating log entries at the given log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

The format string is used to format the values passed in via the variable argument list. The resulting log entry will contain the formatted message and the fields passed in via the variable argument list.

func Printf 

func Printf(format string, v ...any)

Printf is a convenience function for creating log entries at the debug log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

The format string is used to format the values passed in via the variable argument list. The resulting log entry will contain the formatted message and the fields passed in via the variable argument list.

func Println 

func Println(v ...any)

Println is a convenience function for creating log entries at the debug log level. It takes a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Sdebug 

func Sdebug(v ...any) string

Sdebug is a convenience function for creating log entries at the debug log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Sdebugf 

func Sdebugf(format string, v ...any) string

Sdebugf is a convenience function for creating log entries at the debug log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

func Sentry 

func Sentry(level LogLevel, v ...any) string

Sentry is a convenience function for creating log entries at the given log level. It takes a message, and a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Sentryf 

func Sentryf(level LogLevel, format string, v ...any) string

Sentryf is a convenience function for creating log entries at the given log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

The format string is used to format the values passed in via the variable argument list. The resulting log entry will contain the formatted message and the fields passed in via the variable argument list.

func Serror 

func Serror(message string, v ...any) string

Serror is a convenience function for creating log entries at the error log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

The function returns a JSON representation of the log entry as a string.

func Serrorf 

func Serrorf(format string, v ...any) string

Serrorf is a convenience function for creating log entries at the error log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

The format string is used to format the values passed in via the variable argument list. The resulting log entry will contain the formatted message and the fields passed in via the variable argument list.

func SetDefaultLevel 

func SetDefaultLevel(level LogLevel)

SetDefaultLevel sets the default log level for the logger.

The default log level is DEBUG. The default log level can be changed using this function.

The default log level used in the standart log calls, f.e. log.Println. If the default log level is set to NONE, the logger will not write any the standart log calls.

It takes a logLevel value as its argument, which can be any of the following: DEBUG, INFO, WARN, ERROR, or NONE.

The logger will write log messages with the specified log level and above (i.e., if the log level is set to WARN, the logger will write log messages with the log levels WARN and ERROR).

func SetOutput 

func SetOutput(w io.Writer)

SetOutput sets the output destination for the standard logger.

func Sinfo 

func Sinfo(message string, v ...any) string

Sinfo is a convenience function for creating log entries at the info log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Sinfof 

func Sinfof(format string, v ...any) string

Sinfof is a convenience function for creating log entries at the info log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

The format string is used to format the values passed in via the variable argument list. The resulting log entry will contain the formatted message and the fields passed in via the variable argument list.

func Swarn 

func Swarn(message string, v ...any) string

Swarn is a convenience function for creating log entries at the warn log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Swarnf 

func Swarnf(format string, v ...any) string

Swarnf is a convenience function for creating log entries at the warn log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

The format string is used to format the values passed in via the variable argument list. The resulting log entry will contain the formatted message and the fields passed in via the variable argument list.

func Warn 

func Warn(v ...any)

Warn is a convenience function for creating log entries at the warn log level. It takes a variable argument list of maps, allowing the caller to pass in any number of fields to be included in the log entry. The first map in the list is used as the fields for the log entry.

func Warnf 

func Warnf(format string, v ...any)

Warnf is a convenience function for creating log entries at the warn log level. It takes a format string and a variable argument list of values, allowing the caller to pass in any number of values to be included in the log entry. The last value in the list is expected to be a map[string]any, which is used as the fields for the log entry.

Types

type Config 

type Config struct {

	// AppShort is the short name of the application
	AppShort string

	// AppType is the type of the application, f.e. "DEV" or "PROD"
	AppType string

	// UseStdout is a boolean that indicates whether to write log messages to
	// stdout
	UseStdout bool

	// EsConfig is the configuration for the Elasticsearch logger.
	// If nil, the Elasticsearch logger is not used
	*EsConfig

	// File is the configuration for the file logger.
	// If nil, the file logger is not used
	*FileConfig

	// When loger initialized it prints "logger initialized" message. If set
	// this field to true, this message will not be printed.
	DoesNotShowInitMessage bool

	// CustomLogers is some custom loggers, it output will be parsed and added
	// to this loger output.
	CustomLogers []*log.Logger

	// FilterLevel is a list of log levels to filter out.
	FilterLevels []LogLevel
}

Config is a struct that holds configuration information for the logger.

type EsConfig 

type EsConfig struct {
	ES_URL        string // Elasticsearch URL
	ES_API_KEY    string // Elasticsearch API key
	ES_INDEX_NAME string // Elasticsearch index name

	// Time to hold before sending log entries to Elasticsearch.
	// If not set, Default is 5 seconds.
	TimeToHold time.Duration

	// Maximum number of log entries to hold before sending them to Elasticsearch.
	// If not set, Default is 1000.
	EntriesToHold int

	// Directory to store failed batches on disk.
	// If not set, Default is "/tmp/APP_SHORT_NAME/failover".
	FailoverDir string

	// Maximum number of failover files to keep on disk.
	// If not set, Default is 10.
	MaxFailoverFiles int
}

EsConfig is a struct that holds information about how to send log entries to Elasticsearch.

Elasticsearch index creation in Kibana Dev Tools:

Delete existing index:

DELETE /app-name-index

Create new index:

PUT /app-name-index 

{
  "mappings": {
    "properties": {
      "@timestamp": {
        "type": "date_nanos"
      },
      "app_type": {
        "type": "keyword"
      },
      "level": {
        "type": "keyword"
      },
      "message": {
        "type": "text"
      },
      "fields": {
        "type": "object"
      }
    }
  }
}

type Fields 

type Fields map[string]any

Fields is a map of string to any

type FileConfig 

type FileConfig struct {
	// Log files folder
	Folder string

	// Create new log file after
	CreateNewAfter time.Duration

	// Remove old log file after
	RemoveOldAfter time.Duration

	// Remove old log file suffixes, e.g. ".log", ".log.gz".
	// By default if RemoveSuffixes is empty then ".log.gz" is used
	RemoveSuffixes []string
	// contains filtered or unexported fields
}

FileConfig is a struct that holds information about how to send log entries to a file.

type LogEntry 

type LogEntry struct {
	AppType   string         `json:"app_type"` // Prod, Dev, Test or some other
	Timestamp string         `json:"@timestamp"`
	Level     LogLevel       `json:"level"`
	Message   string         `json:"message"`
	Fields    map[string]any `json:"fields,omitempty"`
}

LogEntry is a struct that represents a log entry.

It contains the following fields:

  • Timestamp: the timestamp for the log entry.
  • Level: the log level for the log entry.
  • Message: the log message for the log entry.
  • Fields: a map of additional fields to be included in the log entry.

The String method returns a JSON representation of the log entry.

func (*LogEntry) Json 

func (entry *LogEntry) Json() string

Json returns a JSON representation of a log entry.

It marshals the log entry into a JSON byte slice and returns the JSON representation of the log entry as a string.

func (*LogEntry) String 

func (entry *LogEntry) String() string

String returns a string representation of a log entry.

It formats the log entry as a string in the following format: 

<timestamp> [<level>] <message>[, fields: <fields>]

The timestamp is formatted as per RFC3339. The level is the log level. The message is the log message. The fields are the additional fields that were passed in when creating the log entry.

type LogLevel 

type LogLevel string

LogLevel represents a log level. 

const (
	LevelDebug LogLevel = "DEBUG"
	LevelInfo  LogLevel = "INFO"
	LevelWarn  LogLevel = "WARN"
	LevelError LogLevel = "ERROR"
	LevelNone  LogLevel = ""
)

Log levels

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.