log

package module
v0.1.0-alpha Latest Latest
Warning

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

 Go to latest Published: Mar 8, 2026 License: Apache-2.0 Imports: 23 Imported by: 43

README

Go-Spring :: Log

English | 中文

The project has been officially released, welcome to use!

Go-Spring :: Log is a high-performance and extensible logging library designed specifically for the Go programming language. It offers flexible and structured logging capabilities, including context field extraction, multi-level logging configuration, and multiple output options, making it ideal for a wide range of server-side applications.

Features

  • Multi-Level Logging: Supports standard log levels such as Trace, Debug, Info, Warn, Error, Panic, and Fatal, suitable for debugging and monitoring in various scenarios.
  • Structured Logging: Records logs in a structured format with key fields like trace_id and span_id, making them easy to parse and analyze by log aggregation systems.
  • Context Integration: Extracts additional information from context.Context (e.g., request ID, user ID) and automatically attaches them to log entries.
  • Tag-Based Logging: Introduces a tag system to distinguish logs across different modules or business lines.
  • Plugin Architecture:
    • Appender: Supports multiple output targets including console and file.
    • Layout: Provides both plain text and JSON formatting for log output.
    • Logger: Offers both synchronous and asynchronous loggers; asynchronous mode avoids blocking the main thread.
  • Performance Optimizations: Utilizes buffer management and event pooling to minimize memory allocation overhead.
  • Dynamic Configuration Reload: Supports runtime reloading of logging configurations from external files.
  • Well-Tested: All core modules are covered with unit tests to ensure stability and reliability.

Core Concepts

Tags

Tags are the core concept in this logging library, used to categorize logs. You can register tags via the RegisterTag function and match them with regular expressions. This approach enables a unified logging API without the need to explicitly create logger instances, even for third-party libraries, allowing them to write logs in a standardized way.

Logger

A Logger is the actual component that processes logs. You can retrieve a logger instance using the GetLogger function, mainly for backward compatibility with older projects. This allows you to fetch a logger by name and use the Write function to record pre-formatted messages.

Contextual Field Extraction

You can configure functions to extract contextual data from context.Context and include them in log entries:

  • StringFromContext: extracts string values from the context (e.g., request ID).
  • FieldsFromContext: returns structured fields from the context, such as trace ID or user ID.

Installation

go get github.com/go-spring/log

Quick Start

Here's a simple example demonstrating how to use Go-Spring :: Log:

package main

import (
	"context"

	"github.com/go-spring/log"
)

func main() {
	// Set the function to extract fields from context.
	// You may also use StringFromContext if only strings are needed.
	log.FieldsFromContext = func(ctx context.Context) []log.Field {
		return []log.Field{
			log.String("trace_id", "0a882193682db71edd48044db54cae88"),
			log.String("span_id", "50ef0724418c0a66"),
		}
	}

	// Load configuration file
	err := log.RefreshFile("log.properties")
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	// Record logs
	log.Infof(ctx, log.TagAppDef, "This is an info message")
	log.Errorf(ctx, log.TagBizDef, "This is an error message")

    // Log with structured fields
    log.Info(ctx, log.TagAppDef,
        log.String("key1", "value1"),
        log.Int("key2", 123),
        log.Msg("structured log message"),
    )
}

Configuration

Go-Spring :: Log supports defining logging behavior via JSON, or YAML configuration files. For example:

bufferCap=1KB
bufferSize=1000

appender.file.type=File
appender.file.fileName=log.txt
appender.file.layout.type=JSONLayout

appender.console.type=Console
appender.console.layout.type=TextLayout

logger.root.type=Logger
logger.root.level=warn
logger.root.appenderRef.ref=console

logger.myLogger.type=AsyncLogger
logger.myLogger.level=trace
logger.myLogger.tags=_com_request_in,_com_request_*
logger.myLogger.bufferSize=${bufferSize}
logger.myLogger.appenderRef[0].ref=file

Plugin Development

Go-Spring :: Log offers rich plugin interfaces for developers to easily implement custom Appender, Layout, and Logger components.

License

Go-Spring :: Log is licensed under the Apache License 2.0.

Documentation

Overview

Package log is a high-performance and extensible logging library designed specifically for the Go programming language. It provides flexible and structured logging capabilities, including context field extraction, multi-level logging configuration, and multiple output options, making it ideal for server-side applications.

## Core Concepts:

Tags:

Tags are a core concept in the log package used to categorize logs. By registering a tag via the `RegisterTag` function, you can use regular expressions to match the user-defined tags. This approach allows for a unified API for logging without explicitly creating logger instances. Even third-party libraries can write logs without setting up a logger object.

Loggers:

A Logger is the object that actually handles the logging process. You can obtain a logger instance using the `GetLogger` function, which is mainly provided for compatibility with legacy projects. This allows you to directly retrieve a logger by its name and log pre-formatted messages using the `Write` function.

Context Field Extraction:

Contextual data can be extracted and included in log entries via configurable functions: - `log.StringFromContext`: Extracts a string value (e.g., a request ID) from the context. - `log.FieldsFromContext`: Returns a list of structured fields from the context, such as trace IDs or user IDs.

Configuration from File:

The `log.RefreshFile` function allows loading the logger's configuration from an external file (e.g., yaml or JSON).

Logger Initialization and Logging:

- Using `GetLogger`, you can fetch a logger instance (often for compatibility with older systems). - You can also register custom tags using `RegisterTag` to classify logs according to your needs.

Logging Messages:

The package provides various logging functions, such as `Tracef`, `Debugf`, `Infof`, `Warnf`, etc., which log messages at different levels (e.g., Trace, Debug, Info, Warn). These functions can either accept structured fields or formatted messages.

Structured Logging:

The logger also supports structured logging, where fields are captured as key-value pairs and logged with the message. The fields can be provided directly in the log functions or through a map.

## Examples:

Using a pre-registered tag: 

log.Tracef(ctx, TagRequestOut, "hello %s", "world")
log.Debugf(ctx, TagRequestOut, "hello %s", "world")
log.Infof(ctx, TagRequestIn, "hello %s", "world")
log.Warnf(ctx, TagRequestIn, "hello %s", "world")
log.Errorf(ctx, TagRequestIn, "hello %s", "world")
log.Panicf(ctx, TagRequestIn, "hello %s", "world")
log.Fatalf(ctx, TagRequestIn, "hello %s", "world")

Using structured fields: 

log.Trace(ctx, TagRequestOut, func() []log.Field {
	return []log.Field{
		log.Msgf("hello %s", "world"),
	}
})

log.Error(ctx, TagRequestIn, log.FieldsFromMap(map[string]any{
	"key1": "value1",
	"key2": "value2",
}))

Index

Constants

View Source 
const (
	ValueTypeBool = ValueType(iota)
	ValueTypeInt64
	ValueTypeUint64
	ValueTypeFloat64
	ValueTypeString
	ValueTypeReflect
	ValueTypeArray
	ValueTypeObject
	ValueTypeFromMap
)
View Source 
const (
	BufferFullPolicyBlock         = BufferFullPolicy(0) // Block until space is available
	BufferFullPolicyDiscard       = BufferFullPolicy(1) // Drop the new event or data
	BufferFullPolicyDiscardOldest = BufferFullPolicy(2) // Drop the oldest event or data
)
View Source 
const MsgKey = "msg"
View Source 
const RootLoggerName = "root"

RootLoggerName defines the reserved name for the root logger.

Variables

View Source 
var (
	// TimeNow is an overrideable function to provide custom timestamps.
	// For example, this can be replaced during testing to return a fixed time.
	TimeNow func(ctx context.Context) time.Time

	// StringFromContext is an optional hook to extract a string (e.g., trace ID)
	// from the context. This string will be attached to the log event.
	StringFromContext func(ctx context.Context) string

	// FieldsFromContext is an optional hook to extract structured fields
	// (e.g., trace ID, span ID, or request metadata) from the context.
	FieldsFromContext func(ctx context.Context) []Field
)
View Source 
var (
	// TagAppDef is the default tag for application-related logs.
	TagAppDef = RegisterAppTag("def", "")

	// TagBizDef is the default tag for business-related logs.
	TagBizDef = RegisterBizTag("def", "")
)
View Source 
var (
	NoneLevel  = RegisterLevel(0, "NONE")    // No logging
	TraceLevel = RegisterLevel(100, "TRACE") // Very detailed logging, typically used for debugging
	DebugLevel = RegisterLevel(200, "DEBUG") // Debugging information useful during development
	InfoLevel  = RegisterLevel(300, "INFO")  // General informational messages about application progress
	WarnLevel  = RegisterLevel(400, "WARN")  // Warnings about potential issues or unusual situations
	ErrorLevel = RegisterLevel(500, "ERROR") // Errors that allow the application to continue running
	PanicLevel = RegisterLevel(600, "PANIC") // Severe issues that may cause a panic in the application
	FatalLevel = RegisterLevel(700, "FATAL") // Critical issues that will terminate the application
	MaxLevel   = RegisterLevel(999, "MAX")   // Maximum level (used as the upper bound for comparisons)
)
View Source 
var (
	BufferCap atomic.Int32 // Maximum buffer capacity allowed for reuse
)
View Source 
var Stdout io.Writer = os.Stdout

Stdout is the standard output stream used by appenders.

Functions

func BuildTag added in v0.0.4 

func BuildTag(mainType, subType, action string) string

BuildTag constructs a structured tag string from main type, sub type, and action. The format is: 

_<mainType>_<subType>
_<mainType>_<subType>_<action>

Example: 

BuildTag("app", "startup", "init") -> "_app_startup_init"

func Debug 

func Debug(ctx context.Context, tag *Tag, fn func() []Field)

Debug logs a message at DebugLevel using a lazy field generator. The generator function is only invoked if the level is enabled.

func Debugf 

func Debugf(ctx context.Context, tag *Tag, format string, args ...any)

Debugf logs a formatted message at DebugLevel.

func Destroy added in v0.0.5 

func Destroy()

Destroy gracefully shuts down all loggers and appenders, releasing resources and resetting the global state.

func EncodeFields added in v0.0.10 

func EncodeFields(enc Encoder, fields []Field)

EncodeFields encodes a slice of Fields into the Encoder.

func Error 

func Error(ctx context.Context, tag *Tag, fields ...Field)

Error logs structured fields at ErrorLevel.

func Errorf 

func Errorf(ctx context.Context, tag *Tag, format string, args ...any)

Errorf logs a formatted message at ErrorLevel.

func FastCaller added in v0.1.0 

func FastCaller(skip int) (file string, line int)

FastCaller returns the file name and line number of the calling function. It uses a cache to speed up the lookup.

func Fatal 

func Fatal(ctx context.Context, tag *Tag, fields ...Field)

Fatal logs structured fields at FatalLevel.

func Fatalf 

func Fatalf(ctx context.Context, tag *Tag, format string, args ...any)

Fatalf logs a formatted message at FatalLevel.

func GetAllTags 

func GetAllTags() []string

GetAllTags returns the names of all registered tags.

func Info 

func Info(ctx context.Context, tag *Tag, fields ...Field)

Info logs structured fields at InfoLevel.

func Infof 

func Infof(ctx context.Context, tag *Tag, format string, args ...any)

Infof logs a formatted message at InfoLevel.

func NewPlugin 

func NewPlugin(t reflect.Type, prefix string, s flatten.Storage) (reflect.Value, error)

NewPlugin creates a new plugin instance and injects configuration values.

func Panic 

func Panic(ctx context.Context, tag *Tag, fields ...Field)

Panic logs structured fields at PanicLevel.

func Panicf 

func Panicf(ctx context.Context, tag *Tag, format string, args ...any)

Panicf logs a formatted message at PanicLevel.

func PutEvent 

func PutEvent(e *Event)

PutEvent resets the given Event and returns it to the pool for reuse.

func Record 

func Record(ctx context.Context, level Level, tag *Tag, skip int, fields ...Field)

Record logs a message at the given level for the given tag.

func Refresh added in v0.1.0 

func Refresh(s flatten.Storage) error

Refresh loads a logging configuration from a *flatten.Storage.

func RegisterConverter 

func RegisterConverter[T any](fn Converter[T])

RegisterConverter registers a custom converter for type T.

func RegisterPlugin 

func RegisterPlugin[T any](name string)

RegisterPlugin registers a plugin struct type with a given name and plugin type.

func RegisterProperty added in v0.0.5 

func RegisterProperty(key string, val func(string) error)

RegisterProperty registers a property setter with a given key.

func ToStorage 

func ToStorage(m map[string]string) (map[string]string, error)

ToStorage converts a flattened string map into a *flatten.Storage instance. It interprets keys with a "!" suffix as nested map structures, parsing their values using expr.Parse() and inserting them under a composite key.

Example: 

Input:
  map[string]string{
    "app.name": "MyApp",
    "db!": "{host: localhost, port: 5432}",
  }
Output:
  flatten.Storage{
    "app.name": "MyApp",
    "db.host":  "localhost",
    "db.port":  "5432",
  }

func Trace 

func Trace(ctx context.Context, tag *Tag, fn func() []Field)

Trace logs a message at TraceLevel using a lazy field generator. The generator function is only invoked if the level is enabled.

func Tracef 

func Tracef(ctx context.Context, tag *Tag, format string, args ...any)

Tracef logs a formatted message at TraceLevel.

func Warn 

func Warn(ctx context.Context, tag *Tag, fields ...Field)

Warn logs structured fields at WarnLevel.

func Warnf 

func Warnf(ctx context.Context, tag *Tag, format string, args ...any)

Warnf logs a formatted message at WarnLevel.

func WriteLogString 

func WriteLogString(buf *bytes.Buffer, s string)

WriteLogString escapes and writes a string according to JSON rules.

Types

type Appender 

type Appender interface {
	Lifecycle             // Start/Stop methods for resource management
	GetName() string      // Returns the appender's name
	Append(e *Event)      // Handles writing a log event
	Write(b []byte)       // Directly writes a byte slice
	ConcurrentSafe() bool // Returns true if the appender is concurrent-safe
}

Appender defines components that handle log output. All implementations of Appender must be safe for concurrent use.

type AppenderBase added in v0.0.10 

type AppenderBase struct {
	Name string `PluginAttribute:"name"`
}

AppenderBase provides common configuration fields for all appenders.

func (*AppenderBase) GetName added in v0.0.10 

func (c *AppenderBase) GetName() string

GetName returns the appender's name.

func (*AppenderBase) ReportError 

func (c *AppenderBase) ReportError(err error)

ReportError reports an error to the appender.

type AppenderRef 

type AppenderRef struct {
	Appender
	Ref   string     `PluginAttribute:"ref"`
	Level LevelRange `PluginAttribute:"level,default="`
}

AppenderRef represents a reference to an Appender by name. The actual Appender is resolved and injected during configuration.

func (*AppenderRef) Append added in v0.1.0 

func (c *AppenderRef) Append(e *Event)

Append forwards the event to each child appender.

func (*AppenderRef) Write 

func (c *AppenderRef) Write(b []byte)

Write forwards raw bytes to each child appender.

type AppenderRefs added in v0.1.0 

type AppenderRefs struct {
	AppenderRefs []*AppenderRef `PluginElement:"appenderRef"`
}

AppenderRefs represents a collection of AppenderRef objects.

type ArrayValue 

type ArrayValue interface {
	EncodeArray(enc Encoder)
}

ArrayValue is an interface for types that can be encoded as array.

type AsyncLogger added in v0.0.4 

type AsyncLogger struct {
	LoggerBase
	AppenderRefs

	BufferSize       int              `PluginAttribute:"bufferSize,default=10000"`
	BufferFullPolicy BufferFullPolicy `PluginAttribute:"bufferFullPolicy,default=Discard"`
	// contains filtered or unexported fields
}

AsyncLogger is an asynchronous logger that buffers events and processes them in a dedicated background goroutine.

func (*AsyncLogger) Append added in v0.1.0 

func (c *AsyncLogger) Append(e *Event)

Append enqueues a log event into the buffer. Behavior on full buffer depends on BufferFullPolicy.

func (*AsyncLogger) ConcurrentSafe 

func (c *AsyncLogger) ConcurrentSafe() bool

func (*AsyncLogger) GetDiscardCounter added in v0.0.5 

func (c *AsyncLogger) GetDiscardCounter() int64

GetDiscardCounter returns the total number of discarded events and data.

func (*AsyncLogger) Start added in v0.0.4 

func (c *AsyncLogger) Start() error

Start initializes the AsyncLogger and launches the worker goroutine.

func (*AsyncLogger) Stop added in v0.0.4 

func (c *AsyncLogger) Stop()

Stop gracefully shuts down the async logger.

func (*AsyncLogger) Write added in v0.0.4 

func (c *AsyncLogger) Write(b []byte)

Write enqueues raw bytes into the buffer. Behavior on full buffer depends on BufferFullPolicy.

type BaseLayout 

type BaseLayout struct {
	FileLineLength int `PluginAttribute:"fileLineLength,default=48"`
}

BaseLayout provides common functionality for layouts.

func (*BaseLayout) GetBuffer 

func (c *BaseLayout) GetBuffer() *bytes.Buffer

GetBuffer returns a buffer from the pool (or a new one if empty).

func (*BaseLayout) GetFileLine 

func (c *BaseLayout) GetFileLine(e *Event) string

GetFileLine returns "file:line" string for the log event. If the string is too long, it is truncated and prefixed with "...".

func (*BaseLayout) PutBuffer 

func (c *BaseLayout) PutBuffer(buf *bytes.Buffer)

PutBuffer resets and returns a buffer to the pool, but only if it does not exceed the configured capacity.

type BufferFullPolicy added in v0.0.5 

type BufferFullPolicy int

BufferFullPolicy specifies what to do when an async buffer is full.

func ParseBufferFullPolicy added in v0.0.5 

func ParseBufferFullPolicy(s string) (BufferFullPolicy, error)

ParseBufferFullPolicy converts a string to a BufferFullPolicy.

type CallerType added in v0.1.0 

type CallerType int

CallerType defines the type of caller information to retrieve. 

const (
	// CallerTypeDefault indicates that the caller information should be retrieved
	// using the default method.
	CallerTypeDefault CallerType = iota

	// CallerTypeFast indicates that the caller information should be retrieved
	// using a faster but less accurate method.
	CallerTypeFast

	// CallerTypeNone indicates that no caller information should be retrieved.
	CallerTypeNone
)

type ConsoleAppender 

type ConsoleAppender struct {
	AppenderBase
	Layout Layout `PluginElement:"layout,default=TextLayout"`
}

ConsoleAppender writes formatted log events to standard output.

func (*ConsoleAppender) Append 

func (c *ConsoleAppender) Append(e *Event)

Append formats the event and writes it to standard output.

func (*ConsoleAppender) ConcurrentSafe added in v0.1.0 

func (c *ConsoleAppender) ConcurrentSafe() bool

func (*ConsoleAppender) Start added in v0.1.0 

func (c *ConsoleAppender) Start() error

func (*ConsoleAppender) Stop added in v0.1.0 

func (c *ConsoleAppender) Stop()

func (*ConsoleAppender) Write added in v0.0.4 

func (c *ConsoleAppender) Write(b []byte)

Write writes a byte slice directly to standard output.

type ConsoleLogger added in v0.1.0 

type ConsoleLogger struct {
	LoggerBase
	ConsoleAppender
}

ConsoleLogger writes log events to standard output.

func (*ConsoleLogger) Append added in v0.1.0 

func (c *ConsoleLogger) Append(e *Event)

Append sends the event to the console if the level is enabled.

type Converter 

type Converter[T any] func(string) (T, error)

Converter defines a function that converts a string to type T.

type DiscardAppender 

type DiscardAppender struct {
	AppenderBase
}

DiscardAppender ignores all log events (no-op).

func (*DiscardAppender) Append added in v0.1.0 

func (c *DiscardAppender) Append(e *Event)

func (*DiscardAppender) ConcurrentSafe added in v0.1.0 

func (c *DiscardAppender) ConcurrentSafe() bool

func (*DiscardAppender) Start added in v0.1.0 

func (c *DiscardAppender) Start() error

func (*DiscardAppender) Stop added in v0.1.0 

func (c *DiscardAppender) Stop()

func (*DiscardAppender) Write 

func (c *DiscardAppender) Write(b []byte)

type DiscardLogger added in v0.1.0 

type DiscardLogger struct {
	LoggerBase
	DiscardAppender
}

DiscardLogger ignores all log events (no-op).

type Encoder 

type Encoder interface {
	AppendEncoderBegin()
	AppendEncoderEnd()
	AppendObjectBegin()
	AppendObjectEnd()
	AppendArrayBegin()
	AppendArrayEnd()
	AppendKey(key string)
	AppendBool(v bool)
	AppendInt64(v int64)
	AppendUint64(v uint64)
	AppendFloat64(v float64)
	AppendString(v string)
	AppendReflect(v any)
}

Encoder defines the interface for structured logging encoders. Implementations control how log fields are serialized (e.g. JSON, text).

type Event 

type Event struct {
	Level     Level     // The severity level of the log (e.g., INFO, ERROR, DEBUG)
	Time      time.Time // The timestamp when the event occurred
	File      string    // The source file where the log was triggered
	Line      int       // The line number in the source file
	Tag       string    // A tag used to categorize the log (e.g., subsystem name)
	Fields    []Field   // Custom fields provided specifically for this log event
	CtxString string    // String representation extracted from the context (e.g., trace ID)
	CtxFields []Field   // Additional structured fields extracted from the context (e.g., request ID, user ID)
}

Event represents a single log entry. It contains both the log message context (e.g., time, file, line, tag) and structured metadata (fields and context values).

func GetEvent 

func GetEvent() *Event

GetEvent retrieves an *Event from the pool. If the pool is empty, a new Event will be created.

func (*Event) Reset 

func (e *Event) Reset()

Reset clears the Event's fields so the instance can be reused.

type Field 

type Field struct {
	Key  string    // The field key
	Type ValueType // The type of the value
	Num  uint64    // Holds numeric values or length/bit-representation
	Any  any       // Holds pointers, references, or arbitrary values
}

Field represents a structured log field with a key and a typed value.

func Any 

func Any(key string, value any) Field

Any creates a Field from a value of any type by inspecting its dynamic type. It dispatches to the appropriate typed constructor based on the actual value. If the type is not explicitly handled, it falls back to using Reflect.

func Array 

func Array(key string, val ArrayValue) Field

Array creates a Field with array type, using the ArrayValue interface.

func Bool 

func Bool(key string, val bool) Field

Bool creates a Field for a boolean value.

func BoolPtr 

func BoolPtr(key string, val *bool) Field

BoolPtr creates a Field from a *bool, or Nil if pointer is nil.

func Bools 

func Bools(key string, val []bool) Field

Bools creates a Field with a slice of booleans.

func FieldsFromMap added in v0.0.4 

func FieldsFromMap(m map[string]any) Field

FieldsFromMap creates a special Field that wraps a map[string]any. When encoded, it expands the map into individual key-value fields. This allows existing map structures to be easily converted into log fields without manually iterating through the map and adding each field individually.

func Float 

func Float[T FloatType](key string, val T) Field

Float creates a Field for a float value.

func FloatPtr 

func FloatPtr[T FloatType](key string, val *T) Field

FloatPtr creates a Field from a *float, or Nil if pointer is nil.

func Floats 

func Floats[T FloatType](key string, val []T) Field

Floats creates a Field with a slice of float32 values.

func Int 

func Int[T IntType](key string, val T) Field

Int creates a Field for an integer value.

func IntPtr 

func IntPtr[T IntType](key string, val *T) Field

IntPtr creates a Field from a *int, or Nil if pointer is nil.

func Ints 

func Ints[T IntType](key string, val []T) Field

Ints creates a Field with a slice of integers.

func Msg 

func Msg(msg string) Field

Msg creates a string Field with the fixed key "msg".

func Msgf 

func Msgf(format string, args ...any) Field

Msgf formats a message and creates a Field with the fixed key "msg".

func Nil 

func Nil(key string) Field

Nil creates a Field whose value is nil (Type = ValueTypeReflect).

func Object 

func Object(key string, fields ...Field) Field

Object creates a Field containing a variadic slice of Fields, treated as a nested object.

func Reflect 

func Reflect(key string, val any) Field

Reflect wraps any value into a Field using reflection.

func String 

func String(key string, val string) Field

String creates a Field for a string value.

func StringPtr 

func StringPtr(key string, val *string) Field

StringPtr creates a Field from a *string, or Nil if pointer is nil.

func Strings 

func Strings(key string, val []string) Field

Strings creates a Field with a slice of strings.

func Uint 

func Uint[T UintType](key string, val T) Field

Uint creates a Field for an unsigned integer value.

func UintPtr 

func UintPtr[T UintType](key string, val *T) Field

UintPtr creates a Field from a *uint, or Nil if pointer is nil.

func Uints 

func Uints[T UintType](key string, val []T) Field

Uints creates a Field with a slice of unsigned integers.

func (Field) Encode 

func (f Field) Encode(enc Encoder)

Encode encodes the Field into the Encoder based on its type.

type FileAppender 

type FileAppender struct {
	AppenderBase
	Layout   Layout `PluginElement:"layout,default=TextLayout"`
	FileDir  string `PluginAttribute:"fileDir,default=./logs"`
	FileName string `PluginAttribute:"fileName"`
	// contains filtered or unexported fields
}

FileAppender writes formatted log events to a specified file.

func (*FileAppender) Append 

func (c *FileAppender) Append(e *Event)

Append formats the log event and writes it to the file.

func (*FileAppender) ConcurrentSafe added in v0.1.0 

func (c *FileAppender) ConcurrentSafe() bool

func (*FileAppender) Start 

func (c *FileAppender) Start() error

Start opens the log file for appending.

func (*FileAppender) Stop 

func (c *FileAppender) Stop()

Stop flushes and closes the file.

func (*FileAppender) Write added in v0.0.4 

func (c *FileAppender) Write(b []byte)

Write writes a byte slice directly to the file.

type FileLogger added in v0.1.0 

type FileLogger struct {
	LoggerBase
	FileAppender
}

FileLogger writes log events to a file.

func (*FileLogger) Append added in v0.1.0 

func (c *FileLogger) Append(e *Event)

Append writes the event to the file if the level is enabled.

type FloatType 

type FloatType interface {
	~float32 | ~float64
}

FloatType is the type of float32, float64.

type HumanizeBytes 

type HumanizeBytes int

HumanizeBytes represents a human-readable byte size

func ParseHumanizeBytes 

func ParseHumanizeBytes(s string) (HumanizeBytes, error)

ParseHumanizeBytes converts a human-readable byte string (e.g., "10KB") to an integer.

type IntType 

type IntType interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64
}

IntType is the type of int, int8, int16, int32, int64.

type JSONEncoder 

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

JSONEncoder encodes log fields into standard JSON format.

func NewJSONEncoder 

func NewJSONEncoder(buf *bytes.Buffer) *JSONEncoder

NewJSONEncoder creates a new JSONEncoder.

func (*JSONEncoder) AppendArrayBegin 

func (enc *JSONEncoder) AppendArrayBegin()

AppendArrayBegin writes the beginning of a JSON array.

func (*JSONEncoder) AppendArrayEnd 

func (enc *JSONEncoder) AppendArrayEnd()

AppendArrayEnd writes the end of a JSON array.

func (*JSONEncoder) AppendBool 

func (enc *JSONEncoder) AppendBool(v bool)

AppendBool writes a boolean value.

func (*JSONEncoder) AppendEncoderBegin 

func (enc *JSONEncoder) AppendEncoderBegin()

AppendEncoderBegin writes the start of an encoder section.

func (*JSONEncoder) AppendEncoderEnd 

func (enc *JSONEncoder) AppendEncoderEnd()

AppendEncoderEnd writes the end of an encoder section.

func (*JSONEncoder) AppendFloat64 

func (enc *JSONEncoder) AppendFloat64(v float64)

AppendFloat64 writes a float64 value.

func (*JSONEncoder) AppendInt64 

func (enc *JSONEncoder) AppendInt64(v int64)

AppendInt64 writes an int64 value.

func (*JSONEncoder) AppendKey 

func (enc *JSONEncoder) AppendKey(key string)

AppendKey writes a JSON key.

func (*JSONEncoder) AppendObjectBegin 

func (enc *JSONEncoder) AppendObjectBegin()

AppendObjectBegin writes the beginning of a JSON object.

func (*JSONEncoder) AppendObjectEnd 

func (enc *JSONEncoder) AppendObjectEnd()

AppendObjectEnd writes the end of a JSON object.

func (*JSONEncoder) AppendReflect 

func (enc *JSONEncoder) AppendReflect(v any)

AppendReflect marshals any Go value to JSON and writes it. If marshalling fails, the error message is written as a string.

func (*JSONEncoder) AppendString 

func (enc *JSONEncoder) AppendString(v string)

AppendString writes a string value with proper escaping.

func (*JSONEncoder) AppendUint64 

func (enc *JSONEncoder) AppendUint64(u uint64)

AppendUint64 writes an uint64 value.

func (*JSONEncoder) Reset 

func (enc *JSONEncoder) Reset()

Reset resets the encoder's state.

type JSONLayout 

type JSONLayout struct {
	BaseLayout
}

JSONLayout formats a log event as a structured JSON object.

func (*JSONLayout) ToBytes 

func (c *JSONLayout) ToBytes(e *Event) []byte

ToBytes converts a log event to JSON representation.

type JSONTokenType added in v0.0.10 

type JSONTokenType int

JSONTokenType represents the type of the last token written to JSONEncoder. It is used to determine when separators (commas) are required. 

const (
	JSONTokenUnknown JSONTokenType = iota
	JSONTokenObjectBegin
	JSONTokenObjectEnd
	JSONTokenArrayBegin
	JSONTokenArrayEnd
	JSONTokenKey
	JSONTokenValue
)

type Layout 

type Layout interface {
	ToBytes(e *Event) []byte
}

Layout defines how a log event is formatted into bytes.

type Level 

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

Level represents a logging severity level. Each level has a numeric code (for comparison) and a string name (for display).

func RegisterLevel added in v0.0.6 

func RegisterLevel(code int32, name string) Level

RegisterLevel defines a new logging Level with the given code and name. The Level is also stored in the global levels map for string lookups. Name is normalized to uppercase for consistency.

func (Level) Code added in v0.0.6 

func (l Level) Code() int32

Code returns the numeric code of the Level. Levels with higher codes represent higher severity.

func (Level) Name 

func (l Level) Name() string

Name returns the string name of the Level.

type LevelRange added in v0.1.0 

type LevelRange struct {
	MinLevel Level
	MaxLevel Level
}

LevelRange represents a range of log levels [MinLevel, MaxLevel).

func ParseLevelRange added in v0.1.0 

func ParseLevelRange(s string) (LevelRange, error)

ParseLevelRange parses a string into a LevelRange.

Supported formats: 

""           → [NONE, MAX)
"INFO"       → [INFO, MAX)
"INFO~ERROR" → [INFO, ERROR)

The comparison is case-insensitive. Returns an error for unknown levels.

func (LevelRange) Enable added in v0.1.0 

func (c LevelRange) Enable(l Level) bool

Enable returns true if the given Level 'l' falls within the LevelRange. The check is inclusive of MinLevel and exclusive of MaxLevel.

type Lifecycle 

type Lifecycle interface {
	Start() error
	Stop()
}

Lifecycle is an optional interface for plugin lifecycle hooks.

type Logger 

type Logger interface {
	Appender
	GetTags() []string
	GetLevel() LevelRange
}

Logger is the interface implemented by all loggers.

type LoggerBase added in v0.0.10 

type LoggerBase struct {
	Name   string     `PluginAttribute:"name"`           // Logger name
	Tags   []string   `PluginAttribute:"tags,default="`  // Optional tags
	Level  LevelRange `PluginAttribute:"level,default="` // Logger level range
	Layout Layout     `PluginElement:"layout?"`          // Layout for formatting logs
}

LoggerBase contains fields shared by all logger configurations.

func (*LoggerBase) GetLevel added in v0.1.0 

func (c *LoggerBase) GetLevel() LevelRange

GetLevel returns the level range of the logger.

func (*LoggerBase) GetName added in v0.0.10 

func (c *LoggerBase) GetName() string

GetName returns the name of the logger.

func (*LoggerBase) GetTags added in v0.1.0 

func (c *LoggerBase) GetTags() []string

GetTags returns the tags of the logger.

type LoggerWrapper added in v0.0.4 

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

LoggerWrapper wraps a Logger instance and allows atomic replacement of the underlying Logger at runtime. This ensures that concurrent readers always see a consistent Logger reference without needing locks.

func GetLogger added in v0.0.4 

func GetLogger(name string) *LoggerWrapper

GetLogger retrieves an existing LoggerWrapper by name, or creates a new one if it does not exist yet.

This function must be called only during the initialization phase. It panics if called after global.init is set, indicating that the logging system has already been finalized.

func (*LoggerWrapper) Write added in v0.0.4 

func (m *LoggerWrapper) Write(b []byte) (n int, err error)

Write forwards the given byte slice to the currently active Logger. It implements the io.Writer interface, allowing LoggerWrapper to be used anywhere an io.Writer is expected.

type Plugin 

type Plugin struct {
	Name  string       // Name of the plugin
	Class reflect.Type // Underlying struct type
	File  string       // File where plugin was registered
	Line  int          // Line number where plugin was registered
}

Plugin represents metadata about a plugin type.

type PluginTag 

type PluginTag string

PluginTag is a wrapper for parsing struct field tags.

func (PluginTag) Get 

func (tag PluginTag) Get(key string) string

Get returns the value for a key or the first unnamed value.

func (PluginTag) Lookup 

func (tag PluginTag) Lookup(key string) (value string, ok bool)

Lookup returns the value of a key in a tag and a boolean indicating existence.

type RollingFileAppender added in v0.1.0 

type RollingFileAppender struct {
	AppenderBase
	Layout   Layout        `PluginElement:"layout,default=TextLayout"`
	FileDir  string        `PluginAttribute:"fileDir,default=./logs"`
	FileName string        `PluginAttribute:"fileName"`
	Interval time.Duration `PluginAttribute:"interval,default=1h"`
	MaxAge   time.Duration `PluginAttribute:"maxAge,default=168h"`
	Lock     bool          `PluginAttribute:"lock,default=false"`
	// contains filtered or unexported fields
}

RollingFileAppender writes logs to files that rotate based on time. It is safe for multiple goroutines to call Write() concurrently only if Lock=true. If Lock=false, concurrent writes must be serialized by the caller (e.g., async logger).

func (*RollingFileAppender) Append added in v0.1.0 

func (c *RollingFileAppender) Append(e *Event)

Append formats the log event and writes it to the current file.

func (*RollingFileAppender) ConcurrentSafe added in v0.1.0 

func (c *RollingFileAppender) ConcurrentSafe() bool

func (*RollingFileAppender) Start added in v0.1.0 

func (c *RollingFileAppender) Start() error

Start opens the initial log file and prepares for rotation.

func (*RollingFileAppender) Stop added in v0.1.0 

func (c *RollingFileAppender) Stop()

Stop flushes and closes the current file.

func (*RollingFileAppender) Write 

func (c *RollingFileAppender) Write(b []byte)

Write writes bytes to the current log file. Lock=true ensures thread safety internally; Lock=false assumes caller serializes writes.

type RollingFileLogger added in v0.1.0 

type RollingFileLogger struct {
	LoggerBase

	// File output configuration
	FileDir  string `PluginAttribute:"fileDir,default=./logs"`
	FileName string `PluginAttribute:"fileName,default=app.log"`

	// If true, warning/error logs go to a separate .wf file.
	Separate bool `PluginAttribute:"separate,default=false"`

	// Rotation and retention
	Interval time.Duration `PluginAttribute:"interval,default=1h"`
	MaxAge   time.Duration `PluginAttribute:"maxAge,default=168h"`

	// Async logging options
	AsyncWrite       bool             `PluginAttribute:"async,default=false"`
	BufferSize       int              `PluginAttribute:"bufferSize,default=10000"`
	BufferFullPolicy BufferFullPolicy `PluginAttribute:"bufferFullPolicy,default=Discard"`
	// contains filtered or unexported fields
}

RollingFileLogger writes log events to files with optional rotation, separation, and async behavior.

func (*RollingFileLogger) Append added in v0.1.0 

func (f *RollingFileLogger) Append(e *Event)

Append forwards the event to the underlying logger.

func (*RollingFileLogger) ConcurrentSafe 

func (f *RollingFileLogger) ConcurrentSafe() bool

func (*RollingFileLogger) Start added in v0.1.0 

func (f *RollingFileLogger) Start() error

Start initializes the RollingFileLogger, either synchronous or asynchronous.

func (*RollingFileLogger) Stop added in v0.1.0 

func (f *RollingFileLogger) Stop()

Stop stops all appenders.

func (*RollingFileLogger) Write 

func (f *RollingFileLogger) Write(b []byte)

Write forwards raw bytes to the underlying logger.

type RollingFileWriter added in v0.1.0 

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

RollingFileWriter is the low-level sequential writer. It is NOT safe for concurrent use; synchronization is the responsibility of the caller/appender.

func (*RollingFileWriter) Close added in v0.1.0 

func (w *RollingFileWriter) Close()

Close closes the current file.

func (*RollingFileWriter) Rotate added in v0.1.0 

func (w *RollingFileWriter) Rotate() (*os.File, error)

Rotate checks if a new file needs to be created and returns the current file. Old files are closed in a delayed goroutine. Concurrency must be handled externally.

type SyncLogger added in v0.0.4 

type SyncLogger struct {
	LoggerBase
	AppenderRefs
}

SyncLogger is a synchronous logger that immediately forwards events to appenders.

func (*SyncLogger) Append added in v0.1.0 

func (c *SyncLogger) Append(e *Event)

Append sends the event directly to appenders (blocking).

func (*SyncLogger) ConcurrentSafe 

func (c *SyncLogger) ConcurrentSafe() bool

func (*SyncLogger) Start added in v0.0.4 

func (c *SyncLogger) Start() error

func (*SyncLogger) Stop added in v0.0.4 

func (c *SyncLogger) Stop()

func (*SyncLogger) Write added in v0.0.4 

func (c *SyncLogger) Write(b []byte)

Write writes raw bytes directly to appenders.

type Tag 

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

Tag represents a named log tag, used to categorize logs by subsystem, business domain, or RPC interaction, and so on. Each Tag holds a reference to a Logger.

func RegisterAppTag added in v0.0.4 

func RegisterAppTag(subType, action string) *Tag

RegisterAppTag registers or retrieves a Tag intended for application-layer logs.

  • subType: component or module name
  • action: lifecycle phase or behavior (optional)

func RegisterBizTag added in v0.0.4 

func RegisterBizTag(subType, action string) *Tag

RegisterBizTag registers or retrieves a Tag intended for business-logic logs.

  • subType: business domain or feature name
  • action: operation being logged (optional)

func RegisterRPCTag added in v0.0.4 

func RegisterRPCTag(subType, action string) *Tag

RegisterRPCTag registers or retrieves a Tag intended for RPC logs, covering external/internal dependency interactions.

  • subType: protocol or target system (e.g., http, grpc, redis)
  • action: RPC phase (e.g., send, retry, fail)

func RegisterTag added in v0.0.4 

func RegisterTag(tag string) *Tag

RegisterTag retrieves or creates a Tag by name. If the tag is not yet registered, it is associated with initLogger. Panics if called after global.init is set (i.e., after logging refresh).

Normally, higher-level helpers like RegisterAppTag, RegisterBizTag, or RegisterRPCTag should be used to ensure semantic consistency.

type TextEncoder 

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

TextEncoder encodes fields as "key=value" pairs separated by a delimiter. Nested arrays/objects are serialized as JSON using an internal JSONEncoder.

func NewTextEncoder 

func NewTextEncoder(buf *bytes.Buffer, separator string) *TextEncoder

NewTextEncoder creates a new TextEncoder, using the specified separator.

func (*TextEncoder) AppendArrayBegin 

func (enc *TextEncoder) AppendArrayBegin()

AppendArrayBegin signals the start of a JSON array. Increments the depth and delegates to the JSON encoder.

func (*TextEncoder) AppendArrayEnd 

func (enc *TextEncoder) AppendArrayEnd()

AppendArrayEnd signals the end of a JSON array. Decrements the depth and resets the JSON encoder if back to top level.

func (*TextEncoder) AppendBool 

func (enc *TextEncoder) AppendBool(v bool)

AppendBool appends a boolean value, using JSON encoder if nested.

func (*TextEncoder) AppendEncoderBegin 

func (enc *TextEncoder) AppendEncoderBegin()

AppendEncoderBegin writes the start of an encoder section.

func (*TextEncoder) AppendEncoderEnd 

func (enc *TextEncoder) AppendEncoderEnd()

AppendEncoderEnd writes the end of an encoder section.

func (*TextEncoder) AppendFloat64 

func (enc *TextEncoder) AppendFloat64(v float64)

AppendFloat64 appends a float64 value, using JSON encoder if nested.

func (*TextEncoder) AppendInt64 

func (enc *TextEncoder) AppendInt64(v int64)

AppendInt64 appends an int64 value, using JSON encoder if nested.

func (*TextEncoder) AppendKey 

func (enc *TextEncoder) AppendKey(key string)

AppendKey appends a key for a key-value pair. If inside a JSON structure, the key is handled by the JSON encoder. Otherwise, it's written directly with proper separator handling.

func (*TextEncoder) AppendObjectBegin 

func (enc *TextEncoder) AppendObjectBegin()

AppendObjectBegin signals the start of a JSON object. Increments the depth and delegates to the JSON encoder.

func (*TextEncoder) AppendObjectEnd 

func (enc *TextEncoder) AppendObjectEnd()

AppendObjectEnd signals the end of a JSON object. Decrements the depth and resets the JSON encoder if back to top level.

func (*TextEncoder) AppendReflect 

func (enc *TextEncoder) AppendReflect(v any)

AppendReflect uses reflection to marshal any value as JSON. If nested, delegates to JSON encoder.

func (*TextEncoder) AppendString 

func (enc *TextEncoder) AppendString(v string)

AppendString appends a string value, using JSON encoder if nested.

func (*TextEncoder) AppendUint64 

func (enc *TextEncoder) AppendUint64(v uint64)

AppendUint64 appends a uint64 value, using JSON encoder if nested.

type TextLayout 

type TextLayout struct {
	BaseLayout
}

TextLayout formats a log event as a human-readable text line.

func (*TextLayout) ToBytes 

func (c *TextLayout) ToBytes(e *Event) []byte

ToBytes converts a log event into a plain-text line with separators.

type UintType 

type UintType interface {
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}

UintType is the type of uint, uint8, uint16, uint32, uint64.

type ValueType 

type ValueType int

ValueType represents the underlying type stored in a Field. The Type determines how Num and Any should be interpreted.

Source Files

View all Source files

Directories

Path Synopsis

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.