Skip to content

CLAUDE.md

Latest commit

 

History

History
78 lines (52 loc) · 3.04 KB

CLAUDE.md

File metadata and controls

78 lines (52 loc) · 3.04 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

pingoblin is a Rust TUI application for monitoring latency across Polymarket API endpoints and WebSockets. It displays real-time latency metrics with visual components (sparklines, gauges, percentiles) for developers building Polymarket bots.

Build and Run Commands

# Build
cargo build --release

# Run (default)
cargo run --release

# Run with custom thresholds
cargo run --release -- --warn 50 --critical 100

# Run with CSV export
cargo run --release -- --export-csv metrics.csv

# Run with custom config
cargo run --release -- --config custom-config.toml

# Run tests
cargo test

# Run a single test
cargo test test_name

# Run tests in a specific module
cargo test config::tests

Architecture

Core Flow

  1. main.rs - Entry point that sets up terminal, spawns monitor tasks, and runs the main event loop
  2. Monitor tasks (HTTP and WebSocket) run in separate tokio tasks, sending results via mpsc channels
  3. App state receives metrics and updates the UI at 4 FPS (250ms tick rate)

Module Structure

  • config.rs - Configuration loading from TOML files with CLI argument overrides via clap. Config struct holds monitoring intervals, thresholds, endpoint definitions, and export settings.

  • app.rs - Application state container (App struct). Manages endpoint metrics organized by API group (clob, gamma, data, ws), alert state, and handles keyboard input. Key structs: EndpointMetrics, WsEndpointMetrics, AppState enum.

  • monitor/ - Latency measurement:

    • http.rs - HttpMonitor pings REST endpoints concurrently using reqwest, returns LatencyResult
    • websocket.rs - WebSocketMonitor measures connection time and time-to-first-message using tokio-tungstenite
    • metrics.rs - MetricsCollector and EndpointMetrics for rolling window percentile calculations

  • alerts.rs - AlertManager generates threshold-based alerts (warning/critical/recovery) with deduplication to prevent spam

  • export.rs - MetricsExporter outputs to Prometheus text format, CSV, or JSON

  • ui.rs - Ratatui-based TUI rendering. Draws logo, API sections with gauges/sparklines, WebSocket metrics, alerts, and controls bar

Key Patterns

  • Metrics use a 60-sample rolling window for percentile calculations
  • Endpoints are grouped by API: clob, gamma, data (for HTTP) and separate ws_metrics for WebSockets
  • Color thresholds: Green (<50ms), Yellow (50-100ms), Red (>100ms)
  • Alert state transitions prevent duplicate alerts until recovery

Configuration

Configuration file (config.toml or pingoblin.toml) structure:

  • [monitoring] - interval_ms, history_window_seconds
  • [thresholds] - warning_ms, critical_ms
  • [alerts] - sound_enabled, log_to_file, log_path
  • [export] - prometheus_port, auto_export_csv, csv_path
  • [endpoints.{name}] - base_url, paths array
  • [websockets] - clob, rtds URLs

CLI args (--warn, --critical, --export-csv, --prometheus) override config values.