NyxMon Documentation

Welcome to the NyxMon documentation. NyxMon is a minimalistic monitoring application for services and health checks, designed with a clean architecture approach and SQLite as its storage backend.

Quick Start

1. Install NyxMon with pipx install nyxmon or uv tool install nyxmon

2. Run database migrations: uv run src/django/manage.py migrate

3. Start the agent and dashboard: uvx honcho start

4. Access the dashboard at http://localhost:8000

Note

For detailed installation instructions and development setup, see Installation.

Key Features

• Event-Driven Architecture: Built on a message bus pattern with commands and events

• Multiple Check Types: HTTP checks and DNS checks today (ping and metric validation are planned)

• Django Dashboard: Web interface for monitoring and configuration

• Telegram Notifications: Optional notifications for check failures

• SQLite Backend: Deliberate choice to avoid database dependencies for monitoring

• Async Check Runner: Efficient concurrent check execution

Contents

Guides

• Installation
  • For Users
  • For Developers
  • Database Setup
  • Next Steps
• Usage
  • Starting the Application
  • Managing Checks
  • Notifications
  • Deployment
• Configuration
  • Runtime Settings
  • Check Types
  • Deployment Configuration
  • Repository Configuration
• DNS Check Configuration Examples
  • Configuration Structure
  • Example Configurations
  • Using the CLI
  • Result Data Structure
  • Finding Your Source IP
  • Supported Query Types
  • Best Practices
  • Troubleshooting
• SMTP Check Executor
  • Configuration
  • Behaviour
  • Integration Test Plan (Mail Monitoring PRD)
• IMAP Check Examples
• JSON Metrics Check Examples
  • Fractal Backup Endpoint Integration

Architecture

• Architecture Document - Minimalistic Monitoring Tool
  • Overview
  • System Components
  • Data Flow
• AsyncCheckRunner Execution Flow
  • 1. Entry Point: CheckRunner.run_all
  • 2. Using a Portal to Enter the Async World
  • 3. _async_run_all: Fan Out Work and Gather Results
  • 4. Executor Registry
  • 5. _run_one: Execute a Single Check
  • 6. Returning to the Synchronous Callback
  • 7. Resource Cleanup and Ordering Guarantees
  • 8. Opportunities for Future Refinement
• Runtime Concurrency Model
  • 1. Startup Timeline (entrypoints/cli.py:start_agent)
  • 2. Portal Thread (BlockingPortalProvider)
  • 3. Message Bus and Handlers
  • 4. Collector and Cleaner Threads
  • 5. Worker Thread Pool (anyio.to_thread.run_sync)
  • 6. Streaming Results (anyio.create_memory_object_stream)
  • 7. Concurrency Summary
  • 8. Interaction Between Handlers and Async Code
  • 9. Shutdown

Reference

• API Reference
  • Core Library
  • Runner
  • Notifications

Additional Resources

• Source code: https://github.com/ephes/nyxmon

• Architecture Overview - detailed system design and component documentation

• Async Check Runner - detailed walkthrough of the asynchronous runner implementation