# 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**: 1. Read Architecture Overview to understand the big picture 2. Browse the codebase structure 3. Check Contributing Guidelines 4. Pick a "good first issue" to work on **If you're integrating with OTLP**: 1. Review OTLP Protocol Details 2. Check configuration examples 3. Test with your OpenTelemetry setup 4. See Troubleshooting if needed **If you're extending Gonzo**: 1. Explore Extension Points 2. Review examples in the repository 3. Create your custom formats or skins 4. Share with the community! **If you're optimizing performance**: 1. Understand architecture from Architecture Overview 2. Review performance considerations 3. Profile your specific use case 4. Adjust configuration accordingly ### Architecture at a Glance Gonzo follows a clean, modular architecture: ``` ┌─────────────────────────────────────────────────┐ │ CLI Layer │ │ (Entry Point & Config) │ └─────────────────┬───────────────────────────────┘ │ ┌─────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌──────────┐ │ Input │ │ TUI │ │ AI │ │ Sources │ │ Engine │ │ Engine │ └────┬────┘ └────┬────┘ └────┬─────┘ │ │ │ │ ┌────▼────┐ │ └──────►│Analyzer │◄──────┘ │ Engine │ └────┬────┘ │ ┌────▼────┐ │ Memory │ │ Store │ └─────────┘ ``` #### 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**](https://github.com/charmbracelet/bubbletea) - Terminal UI framework (MVU pattern) * [**Lipgloss**](https://github.com/charmbracelet/lipgloss) - Styling and layout * [**Bubbles**](https://github.com/charmbracelet/bubbles) - Reusable TUI components * [**Cobra**](https://github.com/spf13/cobra) - CLI framework * [**Viper**](https://github.com/spf13/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**: 1. Architecture Overview - Understand structure 2. Development Setup - Set up environment 3. Contribution Guidelines - Follow process #### 2. Implementing OTLP Integration **Goal**: Send logs to Gonzo via OpenTelemetry **Path**: 1. OTLP Protocol Details - Understand implementation 2. Review configuration examples 3. Test integration 4. Troubleshooting - If issues #### 3. Creating Custom Parsers **Goal**: Parse non-standard log formats **Path**: 1. Extension Points - Learn format system 2. Study example formats 3. Create your parser 4. Test and share #### 4. Optimizing Performance **Goal**: Handle high-volume logs efficiently **Path**: 1. Architecture Overview - Understand data flow 2. Review performance sections 3. Adjust buffer sizes and intervals 4. 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](https://semver.org/): * **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](https://github.com/control-theory/gonzo/projects) 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](https://github.com/control-theory/gonzo/issues) * **GitHub Discussions**: [Ask questions](https://github.com/control-theory/gonzo/discussions) * **Email**: #### Contributing Want to contribute to Gonzo's architecture? 1. Review Architecture Overview 2. Check Development Setup 3. Read Contribution Guidelines 4. Start with [good first issues](https://github.com/control-theory/gonzo/labels/good%20first%20issue) ### Additional Resources #### Related Documentation * **Configuration Reference** - Configure Gonzo * **Troubleshooting** - Solve problems * **Contributing** - Join development #### External Resources * **OpenTelemetry**: * **Bubble Tea**: * **Go Documentation**: #### Examples * **Repository**: * **Examples Directory**: * **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 {% hint style="info" %} **New to the codebase?** Start with the Architecture Overview to get a solid understanding of how everything fits together. {% endhint %} {% hint style="success" %} **Building integrations?** The OTLP Protocol Details page has everything you need to connect Gonzo to your OpenTelemetry pipeline. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.controltheory.com/backup/api-and-architecture.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.