Argus: Dynamic Configuration Framework for Go

High-performance configuration management framework for Go applications with zero-allocation performance, universal format support (JSON, YAML, TOML, HCL, INI, Properties), and an ultra-fast CLI powered by Orpheus.

Live Demo

See Argus in action - managing configurations across multiple formats with zero-allocation performance:

Click to view interactive demo

Installation • Quick Start • Performance • Architecture • Framework • Observability • Philosophy • Documentation

Features

• Universal Format Support: JSON, YAML, TOML, HCL, INI, Properties with auto-detection
• ConfigWriter System: Atomic configuration file updates with type-safe operations
• Ultra-Fast CLI: Orpheus-powered CLI
• Professional Grade Validation: With detailed error reporting & performance recommendations
• Security Hardened: Red-team tested against path traversal, injection, DoS and resource exhaustion attacks
• Fuzz Tested: Comprehensive fuzzing for ValidateSecurePath and ParseConfig edge cases
• Zero-Allocation Design: Pre-allocated buffers eliminate GC pressure in hot paths
• Remote Config: Distributed configuration with automatic fallback (Remote → Local). Currently available: HashiCorp Consul, Redis, GitOps with more to come..
• Graceful Shutdown: Timeout-controlled shutdown for Kubernetes and production deployments
• OpenTelemetry Ready: Async tracing and metrics with zero contamination of core library
• Type-Safe Binding: Zero-reflection configuration binding with fluent API (1.6M ops/sec)
• Adaptive Optimization: Five strategies (SingleEvent, SmallBatch, LargeBatch, Light, Auto)
• Unified Audit System: SQLite-based cross-application correlation with JSONL fallback
• Scalable Monitoring: Handle 1-1000+ files simultaneously with linear performance

Compatibility and Support

Argus is designed for Go 1.24+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.

Installation

go get github.com/agilira/argus

Quick Start

Multi-Source Configuration Loading

import "github.com/agilira/argus"

// Load with automatic precedence: ENV vars > File > Defaults
config, err := argus.LoadConfigMultiSource("config.yaml")
if err != nil {
    log.Fatal(err)
}

watcher := argus.New(*config)

Type-Safe Configuration Binding

// Ultra-fast zero-reflection binding (1.6M ops/sec)
var (
    dbHost     string
    dbPort     int
    enableSSL  bool
    timeout    time.Duration
)

err := argus.BindFromConfig(parsedConfig).
    BindString(&dbHost, "database.host", "localhost").
    BindInt(&dbPort, "database.port", 5432).
    BindBool(&enableSSL, "database.ssl", true).
    BindDuration(&timeout, "database.timeout", 30*time.Second).
    Apply()

Real-Time Configuration Updates

// Watch any configuration format - auto-detected
watcher, err := argus.UniversalConfigWatcher("config.yaml", 
    func(config map[string]interface{}) {
        fmt.Printf("Config updated: %+v\n", config)
    })

watcher.Start()
defer watcher.Stop()

Remote Configuration

// Distributed configuration with automatic fallback
remoteManager := argus.NewRemoteConfigWithFallback(
    "https://consul.internal:8500/v1/kv/app/config",  // Primary
    "https://backup-consul.internal:8500/v1/kv/app/config", // Fallback
    "/etc/myapp/fallback.json", // Local fallback
)

watcher := argus.New(argus.Config{
    Remote: remoteManager.Config(),
})

// Graceful shutdown for Kubernetes deployments
defer watcher.GracefulShutdown(30 * time.Second)

Directory Watching

// Watch entire directory for config files with pattern filtering
watcher, err := argus.WatchDirectory("/etc/myapp/config.d", argus.DirectoryWatchOptions{
    Patterns:  []string{"*.yaml", "*.json"},
    Recursive: true,
}, func(update argus.DirectoryConfigUpdate) {
    if update.IsDelete {
        fmt.Printf("Config removed: %s\n", update.FilePath)
    } else {
        fmt.Printf("Config updated: %s\n", update.FilePath)
    }
})
defer watcher.Close()

// Merged config from all files (alphabetical order, later overrides earlier)
watcher, err := argus.WatchDirectoryMerged("/etc/myapp/config.d", argus.DirectoryWatchOptions{
    Patterns: []string{"*.yaml"},
}, func(merged map[string]interface{}, files []string) {
    // 00-base.yaml + 10-override.yaml = merged config
    applyConfig(merged)
})

CLI Usage

# Ultra-fast configuration management CLI
argus config get config.yaml server.port
argus config set config.yaml database.host localhost
argus config convert config.yaml config.json
argus watch config.yaml --interval=1s

Orpheus CLI Integration → - Complete CLI documentation and examples

Performance

Engineered for production environments with sustained monitoring and minimal overhead:

Benchmarks

Configuration Monitoring:      12.10 ns/op     (99.999% efficiency)
Format Auto-Detection:         2.79 ns/op      (universal format support)
JSON Parsing (small):          1,712 ns/op     (616 B/op, 16 allocs/op)
JSON Parsing (large):          7,793 ns/op     (3,064 B/op, 86 allocs/op)
Event Processing:              25.51 ns/op     (BoreasLite single event, CPU-efficient)
Write Operations:              10.15 ns/op     (Ultra-fast file event writing)
vs Go Channels:                5.6x faster     (10.31 ns vs 57.62 ns/op)
CLI Command Parsing:             512 ns/op     (3 allocs/op, Orpheus framework)

Test BoreasLite ring buffer performance:

cd benchmarks && go test -bench="BenchmarkBoreasLite.*" -run=^$ -benchmem

See isolated benchmarks for detailed ring buffer performance analysis.

Scalability (Setup Performance):

File Count    Setup Time    Strategy Used
   50 files    11.92 μs/file  SmallBatch
  500 files    23.95 μs/file  LargeBatch
 1000 files    38.90 μs/file  LargeBatch

Detection rate: 100% across all scales

Optimization Strategies:

Use OptimizationLight for config files that change rarely (daemon processes, CLI tools):

watcher := argus.New(argus.Config{
    PollInterval:         10 * time.Second,
    OptimizationStrategy: argus.OptimizationLight,
})

Architecture

Argus provides intelligent configuration management through polling-based optimization with lock-free stat cache (12.10ns monitoring overhead), ultra-fast format detection (2.79ns per operation).

Complete Architecture Guide →

Parser Support

Built-in parsers optimized for rapid deployment with full specification compliance available via plugins.

Advanced Features: Complex configurations requiring full spec compliance should use plugin parsers via argus.RegisterParser(). See docs/parser-guide.md for details.

Core Framework

ConfigWriter System

Atomic configuration file management with type-safe operations across all supported formats:

// Create writer with automatic format detection
writer, err := argus.NewConfigWriter("config.yaml", argus.FormatYAML, config)
if err != nil {
    return err
}

// Type-safe value operations (zero allocations)
writer.SetValue("database.host", "localhost")
writer.SetValue("database.port", 5432)
writer.SetValue("debug", true)

// Atomic write to disk
if err := writer.WriteConfig(); err != nil {
    return err
}

// Query operations
host := writer.GetValue("database.host")      // 30ns, 0 allocs
keys := writer.ListKeys("database")           // Lists all database.* keys
exists := writer.DeleteValue("old.setting")   // Removes key if exists

Configuration Binding

// Ultra-fast configuration binding - zero reflection
var (
    dbHost     string
    dbPort     int
    enableSSL  bool
    timeout    time.Duration
)

err := argus.BindFromConfig(config).
    BindString(&dbHost, "database.host", "localhost").
    BindInt(&dbPort, "database.port", 5432).
    BindBool(&enableSSL, "database.ssl", true).
    BindDuration(&timeout, "database.timeout", 30*time.Second).
    Apply()

// Variables are now populated and ready to use!

Performance: 1,645,489 operations/second with single allocation per bind

Full API Reference →

Observability & Integrations

Professional OTEL tracing integration with zero core dependency pollution:

// Clean separation: core Argus has no OTEL dependencies
auditLogger, _ := argus.NewAuditLogger(argus.DefaultAuditConfig())

// Optional OTEL wrapper (only when needed)
tracer := otel.Tracer("my-service")
wrapper := NewOTELAuditWrapper(auditLogger, tracer)

// Use either logger or wrapper seamlessly
wrapper.LogConfigChange("/etc/config.json", oldConfig, newConfig)

Complete OTEL Integration Example →

The Philosophy Behind Argus

Argus Panoptes was no ordinary guardian. While others slept, he watched. While others blinked, his hundred eyes remained ever vigilant. Hera chose him not for his strength, but for something rarer—his ability to see everything without ever growing weary.

The giant understood that true protection came not from reactive force, but from constant, intelligent awareness. His vigilance was not frantic or wasteful—each eye served a purpose, each moment of watching was deliberate.

When Zeus finally overcame the great guardian, Hera honored Argus by placing his hundred eyes upon the peacock's tail, ensuring his watchful spirit would endure forever.

Unified Audit Configuration

// Unified SQLite audit (recommended for cross-application correlation)
config := argus.DefaultAuditConfig()  // Uses unified SQLite backend

// Legacy JSONL audit (for backward compatibility)
config := argus.AuditConfig{
    Enabled:    true,
    OutputFile: filepath.Join(os.TempDir(), "argus-audit.jsonl"), // .jsonl = JSONL backend
    MinLevel:   argus.AuditInfo,
}

// Explicit unified SQLite configuration
config := argus.AuditConfig{
    Enabled:    true,
    OutputFile: "",  // Empty = unified SQLite backend
    MinLevel:   argus.AuditCritical,
}

Documentation

Quick Links: - Quick Start Guide - Get running in 2 minutes - Orpheus CLI Integration - Complete CLI documentation and examples - API Reference - Complete API documentation
- Audit System - Comprehensive audit and compliance guide - Examples - Production-ready configuration patterns

License

Argus is licensed under the Mozilla Public License 2.0.

Argus • an AGILira fragment