API & Architecture
Welcome to the API & Architecture section! This documentation provides deep technical insights into how Gonzo works internally, how it implements protocols, and how you can extend it.
Overview
This section is designed for:
Developers who want to understand Gonzo's internals
Contributors who want to add features or fix bugs
Integrators who want to connect Gonzo with other systems
Technical users who want to optimize Gonzo's performance
Curious minds who want to learn how it all works
What You'll Learn
Architecture
Understand Gonzo's design and structure:
Component organization and responsibilities
Data flow through the system
Technology stack and frameworks
Design patterns and decisions
Extension mechanisms
Start here: Architecture Overview
OTLP Protocol
Deep dive into OpenTelemetry Protocol implementation:
gRPC and HTTP transport details
OTLP log data model
Receiver implementation
Configuration and integration
Performance optimization
Start here: OTLP Protocol Details
Extension Points
Learn how to extend Gonzo's functionality:
Custom log format parsers
Custom skins and themes
AI provider integration
Input pipeline extensions
Plugin development (future)
Start here: Extension Points
Quick Navigation
For Different Audiences
If you're a new contributor:
Read Architecture Overview to understand the big picture
Browse the codebase structure
Check Contributing Guidelines
Pick a "good first issue" to work on
If you're integrating with OTLP:
Review OTLP Protocol Details
Check configuration examples
Test with your OpenTelemetry setup
See Troubleshooting if needed
If you're extending Gonzo:
Explore Extension Points
Review examples in the repository
Create your custom formats or skins
Share with the community!
If you're optimizing performance:
Understand architecture from Architecture Overview
Review performance considerations
Profile your specific use case
Adjust configuration accordingly
Architecture at a Glance
Gonzo follows a clean, modular architecture:
Key Components
Input Layer: File readers, stdin, OTLP receivers Processing Layer: Format detection, parsing, analysis Storage Layer: Buffering, frequency tracking Display Layer: Terminal UI with Bubble Tea Integration Layer: AI providers, external systems
Learn more: Architecture Overview
Technology Stack
Core Frameworks
Bubble Tea - Terminal UI framework (MVU pattern)
Lipgloss - Styling and layout
Bubbles - Reusable TUI components
Cobra - CLI framework
Viper - Configuration management
Protocols & Standards
OpenTelemetry - OTLP protocol implementation
gRPC - High-performance RPC framework
Protocol Buffers - Efficient serialization
JSON - Data exchange format
Algorithms & Libraries
drain3 - Log pattern extraction
Go standard library - Core functionality
regex - Pattern matching
Learn more: Architecture Overview
Design Principles
Modularity
Components are loosely coupled and can be modified independently:
Input sources are pluggable
Parsers are format-agnostic
Display is separate from logic
AI providers are abstracted
Performance
Optimized for real-time log processing:
Streaming architecture
Bounded memory usage
Incremental updates
Efficient data structures
Extensibility
Designed to be extended:
Custom format parsers (YAML-based)
Custom skins (YAML-based)
AI provider abstraction
Configuration-driven behavior
User Experience
Terminal UI designed for efficiency:
Keyboard-first navigation
Vim-style shortcuts
Mouse support
Responsive updates
Clear visual hierarchy
Common Use Cases
1. Understanding the Codebase
Goal: Contribute code to Gonzo
Path:
Architecture Overview - Understand structure
Development Setup - Set up environment
Contribution Guidelines - Follow process
2. Implementing OTLP Integration
Goal: Send logs to Gonzo via OpenTelemetry
Path:
OTLP Protocol Details - Understand implementation
Review configuration examples
Test integration
Troubleshooting - If issues
3. Creating Custom Parsers
Goal: Parse non-standard log formats
Path:
Extension Points - Learn format system
Study example formats
Create your parser
Test and share
4. Optimizing Performance
Goal: Handle high-volume logs efficiently
Path:
Architecture Overview - Understand data flow
Review performance sections
Adjust buffer sizes and intervals
Profile and tune
Technical Specifications
System Requirements
Runtime:
Go 1.21 or higher (if building from source)
Modern terminal with Unicode support
256 color support recommended
Resources:
CPU: Minimal (scales with log volume)
Memory: Configurable (default ~50MB)
Network: Optional (for OTLP receiver)
Supported Platforms
Linux: All major distributions
macOS: 10.15 and later
Windows: Windows 10+ (WSL recommended)
Protocol Support
OTLP: v1.0.0+ (gRPC and HTTP)
JSON: Standard JSON format
Logfmt: Key=value format
Plain Text: Basic text logs
Custom: User-defined formats
Performance Characteristics
Throughput
Typical performance (depends on hardware and configuration):
Low volume: <100 logs/sec - Default settings work well
Medium volume: 100-1,000 logs/sec - May need tuning
High volume: 1,000-10,000 logs/sec - Requires optimization
Very high: >10,000 logs/sec - Consider sampling or filtering
Memory Usage
Baseline: ~20-30 MB With 1,000 log buffer: ~30-50 MB With 10,000 log buffer: ~100-200 MB Factors: Log size, attributes, word frequency tracking
Latency
Display updates: Configurable (default 1 second) OTLP ingestion: <10ms per log AI analysis: 1-5 seconds (depends on provider) Search/filter: Near-instant (<100ms)
API Stability
Current Status
Version: 0.1.x (Early stages)
Stability:
CLI Interface: Stable, unlikely to change
Configuration Format: Stable
OTLP Protocol: Stable (follows OpenTelemetry spec)
Internal APIs: May change between versions
Extension APIs: Evolving (formats and skins are stable)
Versioning
Gonzo follows Semantic Versioning:
Major (x.0.0): Breaking changes
Minor (0.x.0): New features (backward compatible)
Patch (0.0.x): Bug fixes (backward compatible)
Future Direction
Planned Enhancements
Near-term:
Enhanced OTLP features
Additional AI providers
Performance optimizations
More built-in formats
Medium-term:
Plugin system architecture
REST API for remote control
Web-based interface option
Advanced analytics
Long-term:
Distributed log analysis
Clustering and aggregation
Machine learning integration
Enterprise features
See Changelog and Roadmap for details.
Getting Help
Documentation
Architecture Overview - System design
OTLP Protocol Details - Protocol implementation
Extension Points - How to extend
Community
GitHub Issues: Report bugs or request features
GitHub Discussions: Ask questions
Email: [email protected]
Contributing
Want to contribute to Gonzo's architecture?
Review Architecture Overview
Check Development Setup
Read Contribution Guidelines
Start with good first issues
Additional Resources
Related Documentation
Configuration Reference - Configure Gonzo
Troubleshooting - Solve problems
Contributing - Join development
External Resources
OpenTelemetry: https://opentelemetry.io/
Bubble Tea: https://github.com/charmbracelet/bubbletea
Go Documentation: https://go.dev/doc/
Examples
Repository: https://github.com/control-theory/gonzo
Examples Directory: https://github.com/control-theory/gonzo/tree/main/examples
Discussions: https://github.com/control-theory/gonzo/discussions
Ready to Dive In?
Choose your path:
📚 Learn the architecture: Start with Architecture Overview
🔌 Implement OTLP: Jump to OTLP Protocol Details
🔧 Extend Gonzo: Explore Extension Points
💻 Contribute code: Check Contributing Guidelines
New to the codebase? Start with the Architecture Overview to get a solid understanding of how everything fits together.
Building integrations? The OTLP Protocol Details page has everything you need to connect Gonzo to your OpenTelemetry pipeline.
Last updated