log Module

The log module provides structured logging powered by Go's slog. It supports levels, structured fields, persistent context, and file rotation in text or JSON format.

Overview

The log module offers:

• Multiple log levels: DEBUG, INFO, WARN, ERROR
• Structured logging: Key-value pairs for machine-readable logs
• Formatted logging: Printf-style formatting with placeholders
• Level management: Set and query current log level
• File output: Write logs to rotating files
• Rotation: Automatic log rotation by size, age, and backup count
• Multiple formats: Text and JSON output
• Persistent context: Add fields that persist across log calls

Functions

Info(values...)

Logs at INFO level. If arguments are key/value pairs (string key), they are logged as structured fields. Otherwise, they are joined into a message.

Returns: - (None, error)

Example:

1
2
3
4

import log

log.Info("service started")
log.Info("user", "42", "action", "login", "ok", true)

Warn(values...)

Logs at WARN level.

Returns: - (None, error)

Example:

1
2
3

import log

log.Warn("cache miss", "key", "sess:1")

Error(values...)

Logs at ERROR level.

Returns: - (None, error)

Example:

1
2
3

import log

log.Error("db down", "retries", 3)

Debug(values...)

Logs at DEBUG level.

Returns: - (None, error)

Example:

1
2
3

import log

log.Debug("details", "module", "auth")

SetLevel(level)

Sets the current log level. Supported values: DEBUG, INFO, WARN, ERROR.

Parameters: - level (string)

Returns: - (None, error)

Example:

1
2
3
4
5

import log

log.SetLevel("WARN")
log.Info("hidden")     // below WARN
log.Warn("visible")

SetOutput(path)

Directs logs to a rotating file with text format using defaults: 10MB max size, 5 backups, 7 days retention, no compression.

Parameters: - path (string): Log file path.

Returns: - (None, error)

Example:

1
2
3
4

import log

log.SetOutput("./logs/app.log")
log.Info("file output configured")

ConfigureRotation(format, path, maxSizeMB, maxBackups, maxAgeDays, compress)

Configures rotation and output format.

Parameters: - format (string): text or json. - path (string): Log file path. - maxSizeMB (int): Max file size in MB before rotation. - maxBackups (int): Number of rotated files to keep. - maxAgeDays (int): Delete files older than this many days (0 disables). - compress (boolean): Gzip rotated files.

Returns: - (None, error)

Example:

1
2
3
4
5
6
7
8
9

import log

// Text handler
log.ConfigureRotation("text", "./logs/app-rotating.log", 50, 10, 14, false)
log.Info("rotation configured")

// JSON handler
log.ConfigureRotation("json", "./logs/app.jsonl", 50, 10, 14, true)
log.Error("failure", "code", 500)

With(key, value)

Adds a persistent structured attribute to the logger. Subsequent logs include this field.

Parameters: - key (string) - value (any)

Returns: - (None, error)

Example:

1
2
3
4
5

import log

log.With("service", "payments")
log.With("instance", "i-12345")
log.Info("startup", true)

Printf(format, args...)

Logs a formatted message at INFO level using fmt-style formatting with placeholders like %s, %d, %v, %f, etc.

Parameters: - format (string): Format string with placeholders - args... (any): Values to substitute into format string

Returns: - (None, error)

Example:

1
2
3
4
5
6

import log

log.Printf("User %s logged in", "Alice")
log.Printf("Processing %d items", 42)
log.Printf("Server started on port %d at %.2f", 8080, 1234567890.123)
log.Printf("Stats: %d requests, %.2f%% success", 1523, 99.54)

GetLevel()

Returns the current logging level as a string.

Returns: - (string, error): Current level (DEBUG, INFO, WARN, or ERROR)

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

import log
import fmt

log.SetLevel("WARN")
var level, err = log.GetLevel()
if err == None {
    fmt.Printf("Current log level: %s\n", level)  // Output: WARN
}

// Check level before logging expensive operations
var currentLevel, _ = log.GetLevel()
if currentLevel == "DEBUG" {
    // Only compute expensive debug info if DEBUG is enabled
    log.Debug("expensive debug data")
}

Quick Reference

Common Patterns

Basic Logging

1
2
3
4
5

import log

log.Info("Application started")
log.Warn("Cache miss")
log.Error("Database connection failed")

Formatted Logging

1
2
3
4

import log

log.Printf("User %s logged in from %s", username, ipAddress)
log.Printf("Processed %d records in %.2f seconds", count, duration)

Structured Logging

1
2
3
4

import log

log.Info("user", "alice", "action", "login", "success", true)
log.Error("error", "db-timeout", "retry", 3, "duration_ms", 5000)

Level Management

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

import log

// Set level
log.SetLevel("DEBUG")

// Check current level
var level, _ = log.GetLevel()
if level == "DEBUG" {
    log.Debug("Detailed debugging information")
}

File Output with Rotation

1
2
3
4
5
6
7

import log

// Simple file output (default rotation)
log.SetOutput("./logs/app.log")

// Advanced rotation configuration
log.ConfigureRotation("json", "./logs/app.jsonl", 50, 10, 14, true)

Persistent Context

1
2
3
4
5
6
7
8
9

import log

// Add persistent fields
log.With("service", "api-gateway")
log.With("version", "1.2.3")

// All subsequent logs include these fields
log.Info("server started")
log.Error("request failed")