Skip to content

Documentation

Wesley Yan S. B. edited this page May 23, 2025 · 8 revisions

πŸ“„ LAGRA Logger - Documentation

LAGRA is a lightweight, fast, and extensible Go logging library inspired by high-performance loggers like Zerolog. It supports structured logging, colorized output, JSON, log levels, asynchronous logging, custom hooks, and more.


πŸš€ Features

βœ… Minimal and fast
βœ… Log levels filtering (Info, Warn, Error)
βœ… Colorized terminal output (customizable)
βœ… JSON log formatting
βœ… Contextual fields in all logs
βœ… Custom timestamp format
βœ… Hooks for additional processing
βœ… Optional asynchronous logging
βœ… File logging support


πŸ“¦ Installation

Since it's your own project, simply import it:

import "github.com/simplyYan/LAGRA"

βš™οΈ Configuration

All options are set through the LagraConfig struct:

type LagraConfig struct {
	LogFile       string            // Path to log file, "" for no file logging.
	EnableColor   bool              // Colorize terminal output.
	MinLevel      LogType           // Minimum log level to output.
	ContextFields map[string]string // Key-value pairs to attach to all logs.
	JSONFormat    bool              // Output logs in JSON.
	TimeFormat    string            // Timestamp format using Go's time layout.
	CustomColors  map[LogType]string// ANSI escape codes for custom colors.
	Async         bool              // Enable asynchronous logging.
}

βœ… Log Levels

const (
	Info  LogType = "INFO"
	Warn  LogType = "WARN"
	Error LogType = "ERROR"
)

The logger will only output logs at or above the configured MinLevel.


πŸ—οΈ Initialization

lagra, err := lagra.NewLagra(lagra.LagraConfig{
	LogFile:       "app.log",
	EnableColor:   true,
	MinLevel:      lagra.Info,
	ContextFields: map[string]string{"app": "LAGRA", "env": "production"},
	JSONFormat:    false,
	TimeFormat:    "2006-01-02 15:04:05",
	Async:         true,
})
if err != nil {
	log.Fatal(err)
}

βœ… If Async is true, logs are processed in a separate goroutine. βœ… Use Close() to safely shut down the logger.


πŸ“€ Logging

Use the provided methods for different log levels:

lagra.Info("Application started")
lagra.Warn("Cache miss")
lagra.Error("Failed to connect to DB")

Each method automatically handles log formatting, colorization, context, and output.


🎨 Color Customization

To override default colors:

lagra.CustomColors: map[lagra.LogType]string{
	lagra.Info:  "\033[34m", // Blue
	lagra.Warn:  "\033[35m", // Magenta
	lagra.Error: "\033[31m", // Red
}

If EnableColor is false, output will be plain text.


πŸ”— Hooks

Attach custom hooks to execute logic every time a log is emitted:

lagra.AddHook(func(level lagra.LogType, msg string) {
	// Example: send log to a remote service
	fmt.Println("HOOK:", level, msg)
})

Multiple hooks are supported and executed in the order they were added.


πŸ“ Output Formats

1. Plain Text (Default)

2025-05-23 14:30:00 [INFO] Application started

With colors if EnableColor = true.


2. JSON Format

If JSONFormat is true, logs will look like:

{
  "time": "2025-05-23 14:30:00",
  "level": "INFO",
  "message": "Application started",
  "app": "LAGRA",
  "env": "production"
}

βœ… Useful for structured logging and log aggregation systems like ELK stack.


⏱️ Custom Time Format

Use Go's time.Format layout:

TimeFormat: "2006-01-02 15:04:05"

For ISO8601:

TimeFormat: time.RFC3339

πŸ“‚ File Logging

If LogFile is set, logs are also written to the specified file.

Example:

LogFile: "app.log"

βœ… Supports concurrent writes in async mode.


⚑ Asynchronous Logging

If Async = true:

  • Logs are pushed to a buffered channel.
  • Background goroutine processes and writes logs.
  • Improves performance in high-throughput systems.

Make sure to call:

lagra.Close()

To gracefully stop the goroutine and close files.


❌ Closing the Logger

Always close LAGRA when shutting down your application:

lagra.Close()

This ensures all buffered logs are flushed.


❓ Example Usage

package main

import (
	"fmt"
	"github.com/simplyYan/LAGRA"
)

func main() {
	logger, _ := lagra.NewLagra(lagra.LagraConfig{
		LogFile:       "logfile.log",
		EnableColor:   true,
		MinLevel:      lagra.Info,
		ContextFields: map[string]string{"service": "auth"},
		JSONFormat:    false,
		TimeFormat:    "2006-01-02 15:04:05",
		Async:         true,
	})

	logger.AddHook(func(level lagra.LogType, msg string) {
		fmt.Println("Custom Hook ->", level, msg)
	})

	logger.Info("Server started")
	logger.Warn("Memory usage high")
	logger.Error("Server crashed")

	logger.Close()
}

πŸ› οΈ How to Contribute

  • Fork the repository
  • Add new features or improvements
  • Submit a pull request with description and examples

πŸ™‹ Support

For questions or suggestions, feel free to reach out or open an issue in your project's repository.


🏁 Summary

LAGRA provides an elegant balance between simplicity and power:

βœ… Structured logs βœ… Fast performance βœ… Highly configurable βœ… Suitable for both CLI tools and web services


Happy logging with LAGRA! πŸš€πŸ–ŠοΈ