mtlog

package module
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2025 License: MIT Imports: 18 Imported by: 0

README

mtlog - Message Template Logging for Go

Go Reference

mtlog is a high-performance structured logging library for Go, inspired by Serilog. It brings message templates and pipeline architecture to the Go ecosystem, achieving zero allocations for simple logging operations while providing powerful features for complex scenarios.

Features

Core Features
  • Zero-allocation logging for simple messages (17.3 ns/op)
  • Message templates with positional property extraction and format specifiers
  • Go template syntax support ({{.Property}}) alongside traditional syntax
  • OpenTelemetry compatibility with support for dotted property names ({http.method}, {service.name})
  • Output templates for customizable log formatting
  • ForType logging with automatic SourceContext from Go types and intelligent caching
  • LogContext scoped properties that flow through operation contexts
  • Source context enrichment with intelligent caching for automatic logger categorization
  • Pipeline architecture for clean separation of concerns
  • Type-safe generics for better compile-time safety
  • LogValue interface for safe logging of sensitive data
  • SelfLog diagnostics for debugging silent failures and configuration issues
  • Standard library compatibility via slog.Handler adapter (Go 1.21+)
  • Kubernetes ecosystem support via logr.LogSink adapter
Sinks & Output
  • Console sink with customizable themes (dark, light, ANSI, Literate)
  • File sink with rolling policies (size, time-based)
  • Seq integration with CLEF format and dynamic level control
  • Elasticsearch sink for centralized log storage and search
  • Splunk sink with HEC (HTTP Event Collector) support
  • Async sink wrapper for high-throughput scenarios
  • Durable buffering with persistent storage for reliability
Pipeline Components
  • Rich enrichment with built-in and custom enrichers
  • Advanced filtering including rate limiting and sampling
  • Minimum level overrides by source context patterns
  • Type-safe capturing with caching for performance
  • Dynamic level control with runtime adjustments
  • Configuration from JSON for flexible deployment

Installation

go get github.com/willibrandon/mtlog

Quick Start

package main

import (
    "github.com/willibrandon/mtlog"
    "github.com/willibrandon/mtlog/core"
)

func main() {
    // Create a logger with console output
    log := mtlog.New(
        mtlog.WithConsole(),
        mtlog.WithMinimumLevel(core.InformationLevel),
    )

    // Simple logging
    log.Info("Application started")
    
    // Message templates with properties
    userId := 123
    log.Info("User {UserId} logged in", userId)
    
    // Capturing complex types
    order := Order{ID: 456, Total: 99.95}
    log.Info("Processing {@Order}", order)
}

// For libraries that need error handling:
func NewLibraryLogger() (*mtlog.Logger, error) {
    return mtlog.Build(
        mtlog.WithConsoleTemplate("[${Timestamp:HH:mm:ss} ${Level:u3}] ${Message}"),
        mtlog.WithMinimumLevel(core.DebugLevel),
    )
}

Visual Example

mtlog with Literate theme

Message Templates

mtlog uses message templates that preserve structure throughout the logging pipeline:

// Properties are extracted positionally
log.Information("User {UserId} logged in from {IP}", userId, ipAddress)

// Go template syntax is also supported
log.Information("User {{.UserId}} logged in from {{.IP}}", userId, ipAddress)

// OTEL-style dotted properties for compatibility with OpenTelemetry conventions
log.Information("HTTP {http.method} to {http.url} returned {http.status_code}", "GET", "/api", 200)
log.Information("Service {service.name} in {service.namespace}", "api", "production")

// Mix both syntaxes as needed
log.Information("User {UserId} ({{.Username}}) from {IP}", userId, username, ipAddress)

// Capturing hints:
// @ - capture complex types into properties
log.Information("Order {@Order} created", order)

// $ - force scalar rendering (stringify)
log.Information("Error occurred: {$Error}", err)

// Format specifiers
log.Information("Processing time: {Duration:F2}ms", 123.456)
log.Information("Disk usage at {Percentage:P1}", 0.85)  // 85.0%
log.Information("Order {OrderId:000} total: ${Amount:F2}", 42, 99.95)

Output Templates

Control how log events are formatted for output with customizable templates. Output templates use ${...} syntax for built-in elements to distinguish them from message template properties:

// Console with custom output template
log := mtlog.New(
    mtlog.WithConsoleTemplate("[${Timestamp:HH:mm:ss} ${Level:u3}] {SourceContext}: ${Message}"),
    mtlog.WithConsoleTheme(sinks.LiterateTheme()),
)

// File with detailed template
log := mtlog.New(
    mtlog.WithFileTemplate("app.log", 
        "[${Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} ${Level:u3}] {SourceContext}: ${Message}${NewLine}${Exception}"),
)
Template Properties
  • ${Timestamp} - Event timestamp with optional format
  • ${Level} - Log level with format options (u3, u, l)
  • ${Message} - Rendered message from template
  • {SourceContext} - Logger context/category
  • ${Exception} - Exception details if present
  • ${NewLine} - Platform-specific line separator
  • Custom properties by name: {RequestId}, {UserId}, etc.
Format Specifiers
  • Timestamps: HH:mm:ss, yyyy-MM-dd, HH:mm:ss.fff
  • Levels: u3 (INF), u (INFORMATION), l (information)
  • Numbers: 000 (zero-pad), F2 (2 decimals), P1 (percentage)
Design Note: Why ${...} for Built-ins?

Unlike Serilog which uses {...} for both built-in elements and properties in output templates, mtlog uses ${...} for built-ins. This design choice prevents ambiguity when user properties have the same names as built-in elements (e.g., a property named "Message" would conflict with the built-in {Message}).

The ${...} syntax provides clear disambiguation:

  • ${Message}, ${Timestamp}, ${Level} - Built-in template elements
  • {UserId}, {OrderId}, {Message} - User properties from your log events

This means you can safely log a property called "Message" without conflicts:

log.Information("Processing {Message} from {Queue}", userMessage, queueName)
// Output template: "[${Timestamp}] ${Level}: ${Message}"
// Result: "[2024-01-15] INF: Processing Hello World from orders"

Pipeline Architecture

The logging pipeline processes events through distinct stages:

Message Template Parser → Enrichment → Filtering → Capturing → Output
Configuration with Functional Options
log := mtlog.New(
    // Output configuration
    mtlog.WithConsoleTheme("dark"),     // Console with dark theme
    mtlog.WithRollingFile("app.log", 10*1024*1024), // Rolling file (10MB)
    mtlog.WithSeq("http://localhost:5341", "api-key"), // Seq integration
    
    // Enrichment
    mtlog.WithTimestamp(),              // Add timestamp
    mtlog.WithMachineName(),            // Add hostname
    mtlog.WithProcessInfo(),            // Add process ID/name
    mtlog.WithCallersInfo(),            // Add file/line info
    
    // Filtering & Level Control
    mtlog.WithMinimumLevel(core.DebugLevel),
    mtlog.WithDynamicLevel(levelSwitch), // Runtime level control
    mtlog.WithFilter(customFilter),
    
    // Capturing
    mtlog.WithCapturing(),          // Enable @ hints
    mtlog.WithCapturingDepth(5),    // Max depth
)

Enrichers

Enrichers add contextual information to all log events:

// Built-in enrichers
log := mtlog.New(
    mtlog.WithTimestamp(),
    mtlog.WithMachineName(),
    mtlog.WithProcessInfo(),
    mtlog.WithEnvironmentVariables("APP_ENV", "VERSION"),
    mtlog.WithThreadId(),
    mtlog.WithCallersInfo(),
    mtlog.WithCorrelationId("RequestId"),
    mtlog.WithSourceContext(), // Auto-detect logger context
)

// Context-based enrichment
ctx := context.WithValue(context.Background(), "RequestId", "abc-123")
log.ForContext("UserId", userId).Information("Processing request")

// Source context for sub-loggers
serviceLog := log.ForSourceContext("MyApp.Services.UserService")
serviceLog.Information("User service started")

// Type-based loggers with automatic SourceContext
userLogger := mtlog.ForType[User](log)
userLogger.Information("User operation") // SourceContext: "User"

orderLogger := mtlog.ForType[OrderService](log)
orderLogger.Information("Processing order") // SourceContext: "OrderService"

LogContext - Scoped Properties

LogContext provides a way to attach properties to a context that will be automatically included in all log events created from loggers using that context. Properties follow a precedence order: event-specific properties (passed directly to log methods) override ForContext properties, which override LogContext properties (set via PushProperty).

// Add properties to context that flow through all operations
ctx := context.Background()
ctx = mtlog.PushProperty(ctx, "RequestId", "req-12345")
ctx = mtlog.PushProperty(ctx, "UserId", userId)
ctx = mtlog.PushProperty(ctx, "TenantId", "acme-corp")

// Create a logger that includes context properties
log := logger.WithContext(ctx)
log.Information("Processing request") // Includes all pushed properties

// Properties are inherited - child contexts get parent properties
func processOrder(ctx context.Context, orderId string) {
    // Add operation-specific properties
    ctx = mtlog.PushProperty(ctx, "OrderId", orderId)
    ctx = mtlog.PushProperty(ctx, "Operation", "ProcessOrder")
    
    log := logger.WithContext(ctx)
    log.Information("Order processing started") // Includes all parent + new properties
}

// Property precedence example
ctx = mtlog.PushProperty(ctx, "UserId", 123)
logger.WithContext(ctx).Information("Test")                          // UserId=123
logger.WithContext(ctx).ForContext("UserId", 456).Information("Test") // UserId=456 (ForContext overrides)
logger.WithContext(ctx).Information("User {UserId}", 789)            // UserId=789 (event property overrides all)

This is particularly useful for:

  • Request tracing in web applications
  • Maintaining context through async operations
  • Multi-tenant applications
  • Batch processing with job-specific context

ForType - Type-Based Logging

ForType provides automatic SourceContext from Go types, making it easy to categorize logs by the types they relate to without manual string constants:

// Automatic SourceContext from type names
userLogger := mtlog.ForType[User](logger)
userLogger.Information("User created") // SourceContext: "User"

productLogger := mtlog.ForType[Product](logger)
productLogger.Information("Product updated") // SourceContext: "Product"

// Works with pointers (automatically dereferenced)
mtlog.ForType[*User](logger).Information("User updated") // SourceContext: "User"

// Service-based logging
type UserService struct {
    logger core.Logger
}

func NewUserService(baseLogger core.Logger) *UserService {
    return &UserService{
        logger: mtlog.ForType[UserService](baseLogger),
    }
}

func (s *UserService) CreateUser(name string) {
    s.logger.Information("Creating user {Name}", name)
    // All logs from this service have SourceContext: "UserService"
}
Advanced Type Naming

For more control over type names, use ExtractTypeName with TypeNameOptions:

// Include package for disambiguation
opts := mtlog.TypeNameOptions{
    IncludePackage: true,
    PackageDepth:   1, // Only immediate package
}
name := mtlog.ExtractTypeName[User](opts) // Result: "myapp.User"
logger := baseLogger.ForContext("SourceContext", name)

// Add prefixes for microservice identification
opts = mtlog.TypeNameOptions{Prefix: "UserAPI."}
name = mtlog.ExtractTypeName[User](opts) // Result: "UserAPI.User"

// Simplify anonymous structs
opts = mtlog.TypeNameOptions{SimplifyAnonymous: true}
name = mtlog.ExtractTypeName[struct{ Name string }](opts) // Result: "AnonymousStruct"

// Disable warnings for production
opts = mtlog.TypeNameOptions{WarnOnUnknown: false}
name = mtlog.ExtractTypeName[interface{}](opts) // Result: "Unknown" (no warning logged)

// Combine multiple options
opts = mtlog.TypeNameOptions{
    IncludePackage:    true,
    PackageDepth:      1,
    Prefix:            "MyApp.",
    Suffix:            ".Handler",
    SimplifyAnonymous: true,
}
Performance & Caching

ForType uses reflection with intelligent caching for optimal performance:

  • ~7% overhead vs manual ForSourceContext (uncached)
  • ~1% overhead with caching enabled (subsequent calls)
  • Thread-safe caching with sync.Map
  • Zero allocations for cached type names
// Performance comparison
ForType[User](logger).Information("User operation")           // ~7% slower than manual
logger.ForSourceContext("User").Information("User operation") // Baseline performance

// But subsequent ForType calls are nearly free due to caching

// Cache statistics for monitoring
stats := mtlog.GetTypeNameCacheStats()
fmt.Printf("Cache hits: %d, misses: %d, evictions: %d, hit ratio: %.1f%%, size: %d/%d", 
    stats.Hits, stats.Misses, stats.Evictions, stats.HitRatio, stats.Size, stats.MaxSize)

// For testing scenarios requiring cache isolation
mtlog.ResetTypeNameCache() // Clears cache and statistics
Multi-Tenant Support

For applications serving multiple tenants, ForType supports tenant-specific cache namespaces:

// Multi-tenant type-based logging with separate cache namespaces
func CreateTenantLogger(baseLogger core.Logger, tenantID string) core.Logger {
    tenantPrefix := fmt.Sprintf("tenant:%s", tenantID)
    return mtlog.ForTypeWithCacheKey[UserService](baseLogger, tenantPrefix)
}

// Each tenant gets separate cache entries
acmeLogger := CreateTenantLogger(logger, "acme-corp")    // Cache key: tenant:acme-corp + UserService
globexLogger := CreateTenantLogger(logger, "globex-inc") // Cache key: tenant:globex-inc + UserService

acmeLogger.Information("Processing acme user")   // SourceContext: "UserService" (acme cache)
globexLogger.Information("Processing globex user") // SourceContext: "UserService" (globex cache)

// Custom type naming per tenant
opts := mtlog.TypeNameOptions{Prefix: "AcmeCorp."}
acmeName := mtlog.ExtractTypeNameWithCacheKey[User](opts, "tenant:acme")
// Result: "AcmeCorp.User" (cached separately per tenant)
Cache Configuration

The type name cache can be configured via environment variables:

# Set cache size limit (default: 10,000 entries)
export MTLOG_TYPE_NAME_CACHE_SIZE=50000  # For large applications
export MTLOG_TYPE_NAME_CACHE_SIZE=1000   # For memory-constrained environments
export MTLOG_TYPE_NAME_CACHE_SIZE=0      # Disable caching entirely

The cache uses LRU (Least Recently Used) eviction when the size limit is exceeded, ensuring memory usage stays bounded while keeping frequently used type names cached.

This is particularly useful for:

  • Large applications with many service types
  • Type-safe logger categorization
  • Automatic SourceContext without string constants
  • Service-oriented architectures
  • Multi-tenant applications requiring cache isolation

Filters

Control which events are logged with powerful filtering:

// Level filtering
mtlog.WithMinimumLevel(core.WarningLevel)

// Minimum level overrides by source context
mtlog.WithMinimumLevelOverrides(map[string]core.LogEventLevel{
    "github.com/gin-gonic/gin":       core.WarningLevel,    // Suppress Gin info logs
    "github.com/go-redis/redis":      core.ErrorLevel,      // Only Redis errors
    "myapp/internal/services":        core.DebugLevel,      // Debug for internal services
    "myapp/internal/services/auth":   core.VerboseLevel,    // Verbose for auth debugging
})

// Custom predicate
mtlog.WithFilter(filters.NewPredicateFilter(func(e *core.LogEvent) bool {
    return !strings.Contains(e.MessageTemplate.Text, "health-check")
}))

// Rate limiting
mtlog.WithFilter(filters.NewRateLimitFilter(100, time.Minute))

// Statistical sampling
mtlog.WithFilter(filters.NewSamplingFilter(0.1)) // 10% of events

// Property-based filtering
mtlog.WithFilter(filters.NewExpressionFilter("UserId", 123))

Sinks

mtlog supports multiple output destinations with advanced features:

Console Sink with Themes
// Literate theme - beautiful, easy on the eyes
mtlog.WithConsoleTheme(sinks.LiterateTheme())

// Dark theme (default)
mtlog.WithConsoleTheme(sinks.DarkTheme())

// Light theme
mtlog.WithConsoleTheme(sinks.LightTheme()) 

// Plain text (no colors)
mtlog.WithConsoleTheme(sinks.NoColorTheme())
File Sinks
// Simple file output
mtlog.WithFileSink("app.log")

// Rolling file by size
mtlog.WithRollingFile("app.log", 10*1024*1024) // 10MB

// Rolling file by time
mtlog.WithRollingFileTime("app.log", time.Hour) // Every hour
Seq Integration
// Basic Seq integration
mtlog.WithSeq("http://localhost:5341")

// With API key
mtlog.WithSeq("http://localhost:5341", "your-api-key")

// Advanced configuration
mtlog.WithSeqAdvanced("http://localhost:5341",
    sinks.WithSeqBatchSize(100),
    sinks.WithSeqBatchTimeout(5*time.Second),
    sinks.WithSeqCompression(true),
)

// Dynamic level control via Seq
levelOption, levelSwitch, controller := mtlog.WithSeqLevelControl(
    "http://localhost:5341",
    mtlog.SeqLevelControllerOptions{
        CheckInterval: 30*time.Second,
        InitialCheck: true,
    },
)
Elasticsearch Integration
// Basic Elasticsearch
mtlog.WithElasticsearch("http://localhost:9200", "logs")

// With authentication
mtlog.WithElasticsearchAdvanced(
    []string{"http://localhost:9200"},
    elasticsearch.WithIndex("myapp-logs"),
    elasticsearch.WithAPIKey("api-key"),
    elasticsearch.WithBatchSize(100),
)
Splunk Integration
// Splunk HEC integration
mtlog.WithSplunk("http://localhost:8088", "your-hec-token")

// Advanced Splunk configuration
mtlog.WithSplunkAdvanced("http://localhost:8088",
    sinks.WithSplunkToken("hec-token"),
    sinks.WithSplunkIndex("main"),
    sinks.WithSplunkSource("myapp"),
)
Async and Durable Sinks
// Wrap any sink for async processing
mtlog.WithAsync(mtlog.WithFileSink("app.log"))

// Durable buffering (survives crashes)
mtlog.WithDurable(
    mtlog.WithSeq("http://localhost:5341"),
    sinks.WithDurableDirectory("./logs/buffer"),
    sinks.WithDurableMaxSize(100*1024*1024), // 100MB buffer
)

Dynamic Level Control

Control logging levels at runtime without restarting your application:

Manual Level Control
// Create a level switch
levelSwitch := mtlog.NewLoggingLevelSwitch(core.InformationLevel)

logger := mtlog.New(
    mtlog.WithLevelSwitch(levelSwitch),
    mtlog.WithConsole(),
)

// Change level at runtime
levelSwitch.SetLevel(core.DebugLevel)

// Fluent interface
levelSwitch.Debug().Information().Warning()

// Check if level is enabled
if levelSwitch.IsEnabled(core.VerboseLevel) {
    // Expensive logging operation
}
Centralized Level Control with Seq
// Automatic level synchronization with Seq server
options := mtlog.SeqLevelControllerOptions{
    CheckInterval: 30 * time.Second,
    InitialCheck:  true,
}

loggerOption, levelSwitch, controller := mtlog.WithSeqLevelControl(
    "http://localhost:5341", options)
defer controller.Close()

logger := mtlog.New(loggerOption)

// Level changes in Seq UI automatically update your application

Configuration from JSON

Configure loggers using JSON for flexible deployments:

// Load from JSON file
config, err := configuration.LoadFromFile("logging.json")
if err != nil {
    log.Fatal(err)
}

logger := config.CreateLogger()

Example logging.json:

{
    "minimumLevel": "Information",
    "sinks": [
        {
            "type": "Console",
            "theme": "dark"
        },
        {
            "type": "RollingFile",
            "path": "logs/app.log",
            "maxSize": "10MB"
        },
        {
            "type": "Seq",
            "serverUrl": "http://localhost:5341",
            "apiKey": "${SEQ_API_KEY}"
        }
    ],
    "enrichers": ["Timestamp", "MachineName", "ProcessInfo"]
}

Safe Logging with LogValue

Protect sensitive data with the LogValue interface:

type User struct {
    ID       int
    Username string
    Password string // Never logged
}

func (u User) LogValue() interface{} {
    return map[string]interface{}{
        "id":       u.ID,
        "username": u.Username,
        // Password intentionally omitted
    }
}

// Password won't appear in logs
user := User{ID: 1, Username: "alice", Password: "secret"}
log.Information("User logged in: {@User}", user)

Performance

Benchmark results on AMD Ryzen 9 9950X:

Operation mtlog zap zerolog Winner
Simple string 16.82 ns 146.6 ns 36.46 ns mtlog
Filtered out 1.47 ns 3.57 ns 1.71 ns mtlog
Two properties 190.6 ns 216.9 ns 49.48 ns zerolog
With context 205.2 ns 130.8 ns 35.25 ns zerolog

Examples

See the examples directory for complete examples:

Ecosystem Compatibility

Standard Library (slog)

mtlog provides full compatibility with Go's standard log/slog package:

// Use mtlog as a backend for slog
slogger := mtlog.NewSlogLogger(
    mtlog.WithSeq("http://localhost:5341"),
    mtlog.WithMinimumLevel(core.InformationLevel),
)

// Use standard slog API
slogger.Info("user logged in", "user_id", 123, "ip", "192.168.1.1")

// Or create a custom slog handler
logger := mtlog.New(mtlog.WithConsole())
slogger = slog.New(logger.AsSlogHandler())
Kubernetes (logr)

mtlog integrates with the Kubernetes ecosystem via logr:

// Use mtlog as a backend for logr
import mtlogr "github.com/willibrandon/mtlog/adapters/logr"

logrLogger := mtlogr.NewLogger(
    mtlog.WithConsole(),
    mtlog.WithMinimumLevel(core.DebugLevel),
)

// Use standard logr API
logrLogger.Info("reconciling", "namespace", "default", "name", "my-app")
logrLogger.Error(err, "failed to update resource")

// Or create a custom logr sink
logger := mtlog.New(mtlog.WithSeq("http://localhost:5341"))
logrLogger = logr.New(logger.AsLogrSink())

Environment Variables

mtlog respects several environment variables for runtime configuration:

Color Control
# Force specific color mode (overrides terminal detection)
export MTLOG_FORCE_COLOR=none     # Disable all colors
export MTLOG_FORCE_COLOR=8        # Force 8-color mode (basic ANSI)
export MTLOG_FORCE_COLOR=256      # Force 256-color mode

# Standard NO_COLOR variable is also respected
export NO_COLOR=1                 # Disable colors (follows no-color.org)
Performance Tuning
# Adjust source context cache size (default: 10000)
export MTLOG_SOURCE_CTX_CACHE=50000  # Increase for large applications
export MTLOG_SOURCE_CTX_CACHE=1000   # Decrease for memory-constrained environments

# Adjust type name cache size (default: 10000)
export MTLOG_TYPE_NAME_CACHE_SIZE=50000  # For applications with many types
export MTLOG_TYPE_NAME_CACHE_SIZE=1000   # For memory-constrained environments
export MTLOG_TYPE_NAME_CACHE_SIZE=0      # Disable type name caching

Tools

mtlog-analyzer

A static analysis tool that catches common mtlog mistakes at compile time:

# Install the analyzer
go install github.com/willibrandon/mtlog/cmd/mtlog-analyzer@latest

# Run with go vet
go vet -vettool=$(which mtlog-analyzer) ./...

The analyzer detects:

  • Template/argument count mismatches
  • Invalid property names (spaces, starting with numbers)
  • Duplicate properties in templates
  • Missing capturing hints for complex types
  • Error logging without error values

Example catches:

// ❌ Template has 2 properties but 1 argument provided
log.Information("User {UserId} logged in from {IP}", userId)

// ❌ Duplicate property 'UserId'
log.Information("User {UserId} did {Action} as {UserId}", id, "login", id)

// ❌ Using @ prefix for basic type
log.Information("Count is {@Count}", 42)

// ✅ Correct usage
log.Information("User {@User} has {Count} items", user, count)

See mtlog-analyzer README for detailed documentation and CI integration.

IDE Extensions
VS Code Extension

For real-time validation in Visual Studio Code, install the mtlog-analyzer extension:

  1. Install mtlog-analyzer: go install github.com/willibrandon/mtlog/cmd/mtlog-analyzer@latest
  2. Install the extension from VS Code Marketplace (search for "mtlog-analyzer")
  3. Get instant feedback on template errors as you type

The extension provides:

  • 🔍 Real-time diagnostics with squiggly underlines
  • 🎯 Precise error locations - click to jump to issues
  • 📊 Three severity levels: errors, warnings, and suggestions
  • 🔧 Quick fixes for common issues (Ctrl+. for PascalCase conversion, argument count fixes)
  • ⚙️ Configurable analyzer path and flags
GoLand Plugin

For real-time validation in GoLand and other JetBrains IDEs with Go support, install the mtlog-analyzer plugin:

  1. Install mtlog-analyzer: go install github.com/willibrandon/mtlog/cmd/mtlog-analyzer@latest
  2. Install the plugin from JetBrains Marketplace (search for "mtlog-analyzer")
  3. Get instant feedback on template errors as you type

The plugin provides:

  • 🔍 Real-time template validation as you type
  • 🎯 Intelligent highlighting (template errors highlight the full string, property warnings highlight just the property)
  • 🔧 Quick fixes for common issues (Alt+Enter for PascalCase conversion, argument count fixes)
  • ⚙️ Configurable analyzer path, flags, and severity levels
  • 🚀 Performance optimized with caching and debouncing
Neovim Plugin

For Neovim users, a comprehensive plugin is included in the repository at neovim-plugin/:

-- Install with lazy.nvim
{
  'willibrandon/mtlog',
  rtp = 'neovim-plugin',
  ft = 'go',
  config = function()
    require('mtlog').setup()
  end,
}

The plugin provides:

  • 🔍 Real-time analysis on save with debouncing
  • 🎯 LSP integration for code actions
  • 🔧 Quick fixes and diagnostic suppression
  • 📊 Statusline integration with diagnostic counts
  • ⚡ Advanced features: queue management, context rules, help system
  • 🚀 Performance optimized with caching and async operations

See the plugin README for detailed configuration and usage.

Advanced Usage

Custom Sinks

Implement the core.LogEventSink interface for custom outputs:

type CustomSink struct{}

func (s *CustomSink) Emit(event *core.LogEvent) error {
    // Process the log event
    return nil
}

log := mtlog.New(
    mtlog.WithSink(&CustomSink{}),
)
Custom Enrichers

Add custom properties to all events:

type UserEnricher struct {
    userID int
}

func (e *UserEnricher) Enrich(event *core.LogEvent, factory core.LogEventPropertyFactory) {
    event.AddPropertyIfAbsent(factory.CreateProperty("UserId", e.userID))
}

log := mtlog.New(
    mtlog.WithEnricher(&UserEnricher{userID: 123}),
)
Type Registration

Register types for special handling during capturing:

capturer := capture.NewDefaultCapturer()
capturer.RegisterScalarType(reflect.TypeOf(uuid.UUID{}))

Documentation

For comprehensive guides and examples, see the docs directory:

Testing

# Run unit tests
go test ./...

# Run integration tests with Docker Compose
docker-compose -f docker/docker-compose.test.yml up -d
go test -tags=integration ./...
docker-compose -f docker/docker-compose.test.yml down

# Run benchmarks (in benchmarks/ folder)
cd benchmarks && go test -bench=. -benchmem

See testing.md for detailed testing guide and manual container setup.

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultTypeNameOptions = TypeNameOptions{
	IncludePackage:    false,
	PackageDepth:      1,
	Prefix:            "",
	Suffix:            "",
	SimplifyAnonymous: false,
	WarnOnUnknown:     true,
}

DefaultTypeNameOptions provides sensible defaults for type name extraction.

Functions

func Build added in v0.2.0 

func Build(opts ...Option) (*logger, error)

Build creates a new logger with the specified options. Returns an error if any option fails during configuration.

func ExtractTypeName added in v0.3.0 

func ExtractTypeName[T any](options TypeNameOptions) string

ExtractTypeName extracts a string representation of the type T using the provided options. This is the exported version of extractTypeName for creating custom loggers.

func ExtractTypeNameWithCacheKey added in v0.3.0 

func ExtractTypeNameWithCacheKey[T any](options TypeNameOptions, cacheKeyPrefix string) string

ExtractTypeNameWithCacheKey extracts a string representation of the type T using the provided options and a custom cache key prefix for multi-tenant scenarios. The cacheKeyPrefix allows for separate cache namespaces, useful in multi-tenant applications where different tenants might have different type naming requirements.

Example usage: 

tenantPrefix := fmt.Sprintf("tenant:%s", tenantID)
name := ExtractTypeNameWithCacheKey[User](options, tenantPrefix)
logger := baseLogger.ForContext("SourceContext", name)

func ForType added in v0.3.0 

func ForType[T any](logger core.Logger) core.Logger

ForType creates a logger with SourceContext automatically set from the type name. The type name is extracted using reflection and provides a convenient way to categorize logs by the types they relate to.

By default, only the type name is used (without package). For example: 

type User struct { Name string }
ForType[User](logger).Information("User created") // SourceContext: "User"
ForType[*User](logger).Information("User updated") // SourceContext: "User" (pointer dereferenced)

This is equivalent to: 

logger.ForContext("SourceContext", "User").Information("User created")

But more convenient and less error-prone for type-specific logging.

Performance: Uses reflection for type name extraction, which incurs a small performance overhead (~7%) compared to manual ForSourceContext. For high-performance scenarios, consider using ForSourceContext with string literals.

Edge Cases:

  • Anonymous structs: Return their full definition (e.g., "struct { Name string }")
  • Interfaces: Return "Unknown" as they have no concrete type name
  • Generic types: Include type parameters (e.g., "GenericType[string]")
  • Built-in types: Return their standard names (e.g., "string", "int", "[]string")
  • Function/channel types: Return their signature (e.g., "func(string) error", "chan string")

For more control over type name formatting, use extractTypeName with custom TypeNameOptions. See createCustomLogger in examples/fortype/main.go for a pattern to create custom loggers with TypeNameOptions for specific naming requirements.

func ForTypeWithCacheKey added in v0.3.0 

func ForTypeWithCacheKey[T any](logger core.Logger, cacheKeyPrefix string) core.Logger

ForTypeWithCacheKey creates a logger with SourceContext automatically set from the type name using a custom cache key prefix. This is useful in multi-tenant scenarios where different tenants might require separate cache namespaces.

Example usage: 

tenantPrefix := fmt.Sprintf("tenant:%s", tenantID)
userLogger := ForTypeWithCacheKey[User](logger, tenantPrefix)
userLogger.Information("User operation") // SourceContext: "User" (cached per tenant)

func GetTypeNameSimple added in v0.3.0 

func GetTypeNameSimple[T any]() string

GetTypeNameSimple is the exported version of getTypeNameSimple for testing and benchmarking.

func GetTypeNameWithPackage added in v0.3.0 

func GetTypeNameWithPackage[T any]() string

GetTypeNameWithPackage is the exported version of getTypeNameWithPackage for testing and benchmarking.

func New 

func New(opts ...Option) *logger

New creates a new logger with the specified options. If any option returns an error during configuration, New will panic. Use Build() for non-panicking initialization.

func NewSlogLogger 

func NewSlogLogger(options ...Option) *slog.Logger

NewSlogLogger creates a new slog.Logger backed by mtlog

func PushProperty added in v0.3.0 

func PushProperty(ctx context.Context, name string, value any) context.Context

PushProperty adds a property to the context that will be included in all log events created from loggers using this context. Properties are inherited - if a context already has properties, the new context will include both the existing and new properties.

Properties set via PushProperty have the lowest precedence and are overridden by ForContext properties and event-specific properties.

Thread Safety: This function is thread-safe. It creates a new context value with a copy of the properties map, ensuring immutability. Multiple goroutines can safely call PushProperty on the same context, and each will receive its own independent context.

Example: 

ctx := context.Background()
ctx = mtlog.PushProperty(ctx, "UserId", 123)
ctx = mtlog.PushProperty(ctx, "TenantId", "acme-corp")

// Both UserId and TenantId will be included in this log
logger.WithContext(ctx).Information("Processing user request")

// Properties can be overridden at more specific scopes
logger.WithContext(ctx).ForContext("UserId", 456).Information("Override test")
// Results in UserId=456 (ForContext overrides PushProperty)

func ResetTypeNameCache added in v0.3.0 

func ResetTypeNameCache()

ResetTypeNameCache clears the type name cache and statistics. Useful for testing and benchmarking.

func WithControlledLevel 

func WithControlledLevel(initialLevel core.LogEventLevel) (Option, *LoggingLevelSwitch)

WithControlledLevel creates a level switch and applies it to the logger. Returns both the option and the level switch for external control.

func WithSeqLevelControl 

func WithSeqLevelControl(serverURL string, options SeqLevelControllerOptions, seqOptions ...sinks.SeqOption) (Option, *LoggingLevelSwitch, *SeqLevelController)

WithSeqLevelControl creates a logger with Seq-controlled dynamic level adjustment. This convenience function sets up both a Seq sink and automatic level control.

Types

type LogBuilder 

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

LogBuilder provides a fluent API for building typed log entries

func (*LogBuilder) Level 

func (b *LogBuilder) Level(level core.LogEventLevel) *LogBuilder

Level sets the log level

func (*LogBuilder) Message 

func (b *LogBuilder) Message(template string) *LogBuilder

Message sets the message template

func (*LogBuilder) Property 

func (b *LogBuilder) Property(name string, value any) *LogBuilder

Property adds a property

func (*LogBuilder) PropertyTyped 

func (b *LogBuilder) PropertyTyped(name string, value any) *LogBuilder

PropertyTyped adds a typed property

func (*LogBuilder) Write 

func (b *LogBuilder) Write()

Write writes the log entry

type LoggerG 

type LoggerG[T any] interface {
	// Logging methods with type safety
	VerboseT(messageTemplate string, value T, args ...any)
	DebugT(messageTemplate string, value T, args ...any)
	InformationT(messageTemplate string, value T, args ...any)
	WarningT(messageTemplate string, value T, args ...any)
	ErrorT(messageTemplate string, value T, args ...any)
	FatalT(messageTemplate string, value T, args ...any)

	// Short method names
	InfoT(messageTemplate string, value T, args ...any)
	WarnT(messageTemplate string, value T, args ...any)

	// ForContextT adds a typed property
	ForContextT(propertyName string, value T) LoggerG[T]
}

LoggerG is a generic type-safe logger interface

func NewTyped 

func NewTyped[T any](opts ...Option) LoggerG[T]

NewTyped creates a new typed logger

type LoggingLevelSwitch 

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

LoggingLevelSwitch provides thread-safe, runtime control of the minimum log level. It enables dynamic adjustment of logging levels without restarting the application.

func NewLoggingLevelSwitch 

func NewLoggingLevelSwitch(initialLevel core.LogEventLevel) *LoggingLevelSwitch

NewLoggingLevelSwitch creates a new logging level switch with the specified initial level.

func (*LoggingLevelSwitch) Debug 

func (ls *LoggingLevelSwitch) Debug() *LoggingLevelSwitch

Debug sets the minimum level to Debug.

func (*LoggingLevelSwitch) Error 

func (ls *LoggingLevelSwitch) Error() *LoggingLevelSwitch

Error sets the minimum level to Error.

func (*LoggingLevelSwitch) Fatal 

func (ls *LoggingLevelSwitch) Fatal() *LoggingLevelSwitch

Fatal sets the minimum level to Fatal.

func (*LoggingLevelSwitch) Information 

func (ls *LoggingLevelSwitch) Information() *LoggingLevelSwitch

Information sets the minimum level to Information.

func (*LoggingLevelSwitch) IsEnabled 

func (ls *LoggingLevelSwitch) IsEnabled(level core.LogEventLevel) bool

IsEnabled returns true if the specified level would be processed with the current minimum level setting.

func (*LoggingLevelSwitch) Level 

func (ls *LoggingLevelSwitch) Level() core.LogEventLevel

Level returns the current minimum log level.

func (*LoggingLevelSwitch) SetLevel 

func (ls *LoggingLevelSwitch) SetLevel(level core.LogEventLevel)

SetLevel updates the minimum log level. This operation is thread-safe and takes effect immediately.

func (*LoggingLevelSwitch) Verbose 

func (ls *LoggingLevelSwitch) Verbose() *LoggingLevelSwitch

Verbose sets the minimum level to Verbose.

func (*LoggingLevelSwitch) Warning 

func (ls *LoggingLevelSwitch) Warning() *LoggingLevelSwitch

Warning sets the minimum level to Warning.

type Option 

type Option func(*config)

Option is a functional option for configuring a logger.

func Debug 

func Debug() Option

Debug sets the minimum level to Debug.

func Error 

func Error() Option

Error sets the minimum level to Error.

func Information 

func Information() Option

Information sets the minimum level to Information.

func Verbose 

func Verbose() Option

Verbose sets the minimum level to Verbose.

func Warning 

func Warning() Option

Warning sets the minimum level to Warning.

func WithAutoSourceContext added in v0.2.0 

func WithAutoSourceContext() Option

WithAutoSourceContext adds automatic source context detection.

func WithCallers 

func WithCallers(skip int) Option

WithCallers adds caller information enrichment.

func WithCallersInfo 

func WithCallersInfo() Option

WithCallersInfo adds caller information enrichment with default skip.

func WithCapturer added in v0.6.0 

func WithCapturer(capturer core.Capturer) Option

WithCapturer sets the capturer for the pipeline.

func WithCapturing added in v0.6.0 

func WithCapturing() Option

WithCapturing adds the cached capturer for better performance.

func WithCapturingDepth added in v0.6.0 

func WithCapturingDepth(maxDepth int) Option

WithCapturingDepth adds capturing with a specific max depth.

func WithCommonEnvironment 

func WithCommonEnvironment() Option

WithCommonEnvironment adds enrichers for common environment variables.

func WithConsole 

func WithConsole() Option

WithConsole adds a console sink.

func WithConsoleProperties 

func WithConsoleProperties() Option

WithConsoleProperties adds a console sink that displays properties.

func WithConsoleTemplate added in v0.2.0 

func WithConsoleTemplate(template string) Option

WithConsoleTemplate adds a console sink with a custom output template.

func WithConsoleTheme added in v0.2.0 

func WithConsoleTheme(theme *sinks.ConsoleTheme) Option

WithConsoleTheme adds a console sink with a custom theme.

func WithCorrelationId 

func WithCorrelationId(correlationId string) Option

WithCorrelationId adds a fixed correlation ID to all log events.

func WithCustomCapturing added in v0.6.0 

func WithCustomCapturing(maxDepth, maxStringLength, maxCollectionCount int) Option

WithCustomCapturing adds a capturer with custom limits.

func WithDurableBuffer 

func WithDurableBuffer(wrapped core.LogEventSink, bufferPath string) Option

WithDurableBuffer adds durable buffering to a sink for reliability.

func WithDurableBufferAdvanced 

func WithDurableBufferAdvanced(wrapped core.LogEventSink, options sinks.DurableOptions) Option

WithDurableBufferAdvanced adds durable buffering with advanced options.

func WithDurableElasticsearch 

func WithDurableElasticsearch(url, bufferPath string) Option

WithDurableElasticsearch adds an Elasticsearch sink with durable buffering.

func WithDurableSeq 

func WithDurableSeq(serverURL, bufferPath string) Option

WithDurableSeq adds a Seq sink with durable buffering.

func WithDurableSplunk 

func WithDurableSplunk(url, token, bufferPath string) Option

WithDurableSplunk adds a Splunk sink with durable buffering.

func WithDynamicLevel 

func WithDynamicLevel(levelSwitch *LoggingLevelSwitch) Option

WithDynamicLevel enables dynamic level control using a level switch. This is an alias for WithLevelSwitch for better readability.

func WithElasticsearch 

func WithElasticsearch(url string) Option

WithElasticsearch adds an Elasticsearch sink with default configuration.

func WithElasticsearchAPIKey 

func WithElasticsearchAPIKey(url, apiKey string) Option

WithElasticsearchAPIKey adds an Elasticsearch sink with API key authentication.

func WithElasticsearchAdvanced 

func WithElasticsearchAdvanced(url string, opts ...sinks.ElasticsearchOption) Option

WithElasticsearchAdvanced adds an Elasticsearch sink with advanced options.

func WithElasticsearchBasicAuth 

func WithElasticsearchBasicAuth(url, username, password string) Option

WithElasticsearchBasicAuth adds an Elasticsearch sink with basic authentication.

func WithEnricher 

func WithEnricher(enricher core.LogEventEnricher) Option

WithEnricher adds an enricher to the pipeline.

func WithEnvironment 

func WithEnvironment(variableName, propertyName string) Option

WithEnvironment adds environment variable enrichment.

func WithEnvironmentVariables 

func WithEnvironmentVariables(variables ...string) Option

WithEnvironmentVariables adds enrichers for multiple environment variables.

func WithExcludeFilter 

func WithExcludeFilter(predicate func(*core.LogEvent) bool) Option

WithExcludeFilter adds a filter that excludes events matching the predicate.

func WithFile 

func WithFile(path string) Option

WithFile adds a file sink.

func WithFileTemplate added in v0.2.0 

func WithFileTemplate(path string, template string) Option

WithFileTemplate adds a file sink with a custom output template.

func WithFilter 

func WithFilter(filter core.LogEventFilter) Option

WithFilter adds a filter to the pipeline.

func WithHashSampling 

func WithHashSampling(propertyName string, rate float32) Option

WithHashSampling adds a hash-based sampling filter.

func WithLevelFilter 

func WithLevelFilter(minimumLevel core.LogEventLevel) Option

WithLevelFilter adds a minimum level filter.

func WithLevelSwitch 

func WithLevelSwitch(levelSwitch *LoggingLevelSwitch) Option

WithLevelSwitch enables dynamic level control using the specified level switch. When a level switch is provided, it takes precedence over the static minimum level.

func WithMachineName 

func WithMachineName() Option

WithMachineName adds machine name enrichment.

func WithMinimumLevel 

func WithMinimumLevel(level core.LogEventLevel) Option

WithMinimumLevel sets the minimum log level.

func WithMinimumLevelOverrides added in v0.2.0 

func WithMinimumLevelOverrides(defaultLevel core.LogEventLevel, overrides map[string]core.LogEventLevel) Option

WithMinimumLevelOverrides adds source context-based level filtering.

func WithProcess 

func WithProcess() Option

WithProcess adds process information enrichment.

func WithProcessInfo 

func WithProcessInfo() Option

WithProcessInfo is an alias for WithProcess.

func WithProperties 

func WithProperties(properties map[string]any) Option

WithProperties adds multiple global properties.

func WithProperty 

func WithProperty(name string, value any) Option

WithProperty adds a global property to all log events.

func WithPropertyFilter 

func WithPropertyFilter(propertyName string, expectedValue any) Option

WithPropertyFilter adds a filter that matches a specific property value.

func WithRateLimit 

func WithRateLimit(maxEvents int, windowNanos int64) Option

WithRateLimit adds a rate limiting filter.

func WithSampling 

func WithSampling(rate float32) Option

WithSampling adds a sampling filter.

func WithSeq 

func WithSeq(serverURL string) Option

WithSeq adds a Seq sink with default configuration.

func WithSeqAPIKey 

func WithSeqAPIKey(serverURL, apiKey string) Option

WithSeqAPIKey adds a Seq sink with API key authentication.

func WithSeqAdvanced 

func WithSeqAdvanced(serverURL string, opts ...sinks.SeqOption) Option

WithSeqAdvanced adds a Seq sink with advanced options.

func WithSink 

func WithSink(sink core.LogEventSink) Option

WithSink adds a sink to the pipeline.

func WithSourceContext added in v0.2.0 

func WithSourceContext(sourceContext string) Option

WithSourceContext adds source context enrichment with the specified context.

func WithSplunk 

func WithSplunk(url, token string) Option

WithSplunk adds a Splunk sink to the logger.

func WithSplunkAdvanced 

func WithSplunkAdvanced(url, token string, opts ...sinks.SplunkOption) Option

WithSplunkAdvanced adds a Splunk sink with advanced options.

func WithThreadId 

func WithThreadId() Option

WithThreadId adds goroutine ID enrichment.

func WithTimestamp 

func WithTimestamp() Option

WithTimestamp adds timestamp enrichment.

type Repository added in v0.3.0 

type Repository interface {
	Save(any) error
}

Repository interface for testing - used across multiple test files

type SeqLevelController 

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

SeqLevelController automatically updates a LoggingLevelSwitch based on the minimum level configured in Seq. This enables centralized level control where Seq acts as the source of truth for log levels.

func NewSeqLevelController 

func NewSeqLevelController(levelSwitch *LoggingLevelSwitch, seqSink *sinks.SeqSink, options SeqLevelControllerOptions) *SeqLevelController

NewSeqLevelController creates a new controller that synchronizes a level switch with Seq's minimum level setting. The controller will periodically query Seq and update the level switch when changes are detected.

func (*SeqLevelController) Close 

func (slc *SeqLevelController) Close()

Close stops the level controller and waits for background operations to complete.

func (*SeqLevelController) ForceCheck 

func (slc *SeqLevelController) ForceCheck() error

ForceCheck immediately queries Seq for the current level and updates the level switch if necessary. This is useful for testing or immediate synchronization.

func (*SeqLevelController) GetCurrentLevel 

func (slc *SeqLevelController) GetCurrentLevel() core.LogEventLevel

GetCurrentLevel returns the current level from the level switch.

func (*SeqLevelController) GetLastSeqLevel 

func (slc *SeqLevelController) GetLastSeqLevel() core.LogEventLevel

GetLastSeqLevel returns the last level retrieved from Seq.

type SeqLevelControllerBuilder 

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

SeqLevelControllerBuilder provides a fluent interface for building Seq level controllers.

func NewSeqLevelControllerBuilder 

func NewSeqLevelControllerBuilder(serverURL string) *SeqLevelControllerBuilder

NewSeqLevelControllerBuilder creates a new builder for Seq level controllers.

func (*SeqLevelControllerBuilder) Build 

func (b *SeqLevelControllerBuilder) Build() (Option, *LoggingLevelSwitch, *SeqLevelController)

Build creates the Seq level controller and returns the logger option, level switch, and controller.

func (*SeqLevelControllerBuilder) WithCheckInterval 

func (b *SeqLevelControllerBuilder) WithCheckInterval(interval time.Duration) *SeqLevelControllerBuilder

WithCheckInterval sets the interval for querying Seq.

func (*SeqLevelControllerBuilder) WithErrorHandler 

func (b *SeqLevelControllerBuilder) WithErrorHandler(onError func(error)) *SeqLevelControllerBuilder

WithErrorHandler sets the error handler for level checking failures.

func (*SeqLevelControllerBuilder) WithInitialCheck 

func (b *SeqLevelControllerBuilder) WithInitialCheck(initialCheck bool) *SeqLevelControllerBuilder

WithInitialCheck controls whether to perform an initial level check.

func (*SeqLevelControllerBuilder) WithLevelSwitch 

func (b *SeqLevelControllerBuilder) WithLevelSwitch(levelSwitch *LoggingLevelSwitch) *SeqLevelControllerBuilder

WithLevelSwitch uses an existing level switch instead of creating a new one.

func (*SeqLevelControllerBuilder) WithSeqAPIKey 

func (b *SeqLevelControllerBuilder) WithSeqAPIKey(apiKey string) *SeqLevelControllerBuilder

WithSeqAPIKey adds API key authentication for Seq.

type SeqLevelControllerOptions 

type SeqLevelControllerOptions struct {
	// CheckInterval is how often to query Seq for level changes.
	// Default: 30 seconds
	CheckInterval time.Duration

	// OnError is called when an error occurs during level checking.
	// Default: no-op
	OnError func(error)

	// InitialCheck determines whether to perform an initial check immediately.
	// Default: true
	InitialCheck bool
}

SeqLevelControllerOptions configures a Seq level controller.

type StructuredLogger 

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

StructuredLogger provides type-safe structured logging

func NewStructured 

func NewStructured(opts ...Option) *StructuredLogger

NewStructured creates a new structured logger

func (*StructuredLogger) Log 

func (sl *StructuredLogger) Log(level core.LogEventLevel, messageTemplate string, properties *core.PropertyBag)

Log logs with a typed property bag

func (*StructuredLogger) LogWith 

func (sl *StructuredLogger) LogWith() *LogBuilder

LogWith logs with typed properties using a builder pattern

type TypeNameCacheStats added in v0.3.0 

type TypeNameCacheStats struct {
	Hits      int64   // Number of cache hits
	Misses    int64   // Number of cache misses
	Evictions int64   // Number of cache evictions due to LRU policy
	HitRatio  float64 // Hit ratio as a percentage (0-100)
	Size      int64   // Number of entries currently in the cache
	MaxSize   int64   // Maximum cache size before eviction
}

TypeNameCacheStats provides performance statistics for the type name cache.

func GetTypeNameCacheStats added in v0.3.0 

func GetTypeNameCacheStats() TypeNameCacheStats

GetTypeNameCacheStats returns current cache performance statistics.

type TypeNameOptions added in v0.3.0 

type TypeNameOptions struct {
	// IncludePackage determines whether to include the package path in the type name.
	// Default: false (only type name)
	IncludePackage bool

	// PackageDepth limits how many package path segments to include when IncludePackage is true.
	// 0 means include full package path. Default: 1 (only immediate package)
	PackageDepth int

	// Prefix is prepended to the type name for consistent naming.
	// Example: "MyApp." would result in "MyApp.User" for User type
	Prefix string

	// Suffix is appended to the type name.
	// Example: ".Service" would result in "User.Service" for User type
	Suffix string

	// SimplifyAnonymous controls how anonymous struct types are displayed.
	// When true, anonymous structs return "AnonymousStruct" instead of their full definition.
	// Default: false (shows full struct definition)
	SimplifyAnonymous bool

	// WarnOnUnknown controls whether to log warnings for "Unknown" type names.
	// When true, warnings are logged to help with debugging interface types and unresolvable types.
	// When false, warnings are suppressed to reduce log noise in production.
	// Default: true (warnings enabled)
	WarnOnUnknown bool
}

TypeNameOptions controls how type names are extracted and formatted for SourceContext.

Use with extractTypeName to create custom loggers with more control over type name formatting than the default ForType function. See examples/fortype/main.go demonstrateTypeNameOptions for practical usage examples.

Example: 

opts := TypeNameOptions{IncludePackage: true, Prefix: "MyApp."}
name := extractTypeName[User](opts) // Result: "MyApp.mypackage.User"
logger := baseLogger.ForContext("SourceContext", name)

type TypedLogger 

type TypedLogger[T any] struct {
	// contains filtered or unexported fields
}

TypedLogger wraps a regular logger with type-safe methods

func (*TypedLogger[T]) DebugT 

func (l *TypedLogger[T]) DebugT(messageTemplate string, value T, args ...any)

DebugT logs at debug level with typed value

func (*TypedLogger[T]) ErrorT 

func (l *TypedLogger[T]) ErrorT(messageTemplate string, value T, args ...any)

ErrorT logs at error level with typed value

func (*TypedLogger[T]) FatalT 

func (l *TypedLogger[T]) FatalT(messageTemplate string, value T, args ...any)

FatalT logs at fatal level with typed value

func (*TypedLogger[T]) ForContextT 

func (l *TypedLogger[T]) ForContextT(propertyName string, value T) LoggerG[T]

ForContextT adds a typed property to the logger context

func (*TypedLogger[T]) InfoT 

func (l *TypedLogger[T]) InfoT(messageTemplate string, value T, args ...any)

InfoT writes an information-level log event with a typed value (alias for InformationT)

func (*TypedLogger[T]) InformationT 

func (l *TypedLogger[T]) InformationT(messageTemplate string, value T, args ...any)

InformationT logs at information level with typed value

func (*TypedLogger[T]) VerboseT 

func (l *TypedLogger[T]) VerboseT(messageTemplate string, value T, args ...any)

VerboseT logs at verbose level with typed value

func (*TypedLogger[T]) WarnT 

func (l *TypedLogger[T]) WarnT(messageTemplate string, value T, args ...any)

WarnT writes a warning-level log event with a typed value (alias for WarningT)

func (*TypedLogger[T]) WarningT 

func (l *TypedLogger[T]) WarningT(messageTemplate string, value T, args ...any)

WarningT logs at warning level with typed value

type UserRepository added in v0.3.0 

type UserRepository struct{}

UserRepository implements Repository for testing

func (*UserRepository) Save added in v0.3.0 

func (ur *UserRepository) Save(any) error

Source Files

View all Source files

Directories

Path Synopsis
cmd
mtlog-analyzer module
Package core provides the fundamental interfaces and types for mtlog.
 Package core provides the fundamental interfaces and types for mtlog.
examples
async command
basic command
capturing command
configuration command
context command
durable command
dynamic-levels command
elasticsearch command
enrichers command
filtering command
fortype command
Package main demonstrates using ForType for automatic SourceContext from type names.
 Package main demonstrates using ForType for automatic SourceContext from type names.
generics command
go-templates command
logcontext command
Package main demonstrates using LogContext for scoped properties.
 Package main demonstrates using LogContext for scoped properties.
logvalue command
otel command
Package main demonstrates using OTEL-style dotted property names with mtlog.
 Package main demonstrates using OTEL-style dotted property names with mtlog.
output-templates command
rolling command
seq command
showcase command
splunk command
themes command
goland-plugin
src/test/resources/testData command
internal
capture
enrichers
filters
formatters
formatters/output
handler
parser
Package selflog provides internal diagnostic logging for mtlog.
 Package selflog provides internal diagnostic logging for mtlog.

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.