How whileone-techsoft/perfspect works
Project type and purpose
• Project type: An open-source, command-line performance analysis tool written in Go.
• Purpose: Collects hardware/software telemetry (metrics, reports, flamegraphs, lock contention, config), processes data, and renders reports (HTML, CSV, JSON, text) or exposes a Prometheus endpoint.
File structure
• Top-level artifacts:
• cmd/…: Subcommands (metrics, report, telemetry, flame, lock, config, root) – implements the CLI “command” pattern.
• internal/…: Core libraries (common utilities, target abstraction, scripting, progress spinners, report rendering, table helpers).
• builder/: Docker-based build scripts for reproducible builds.
• tools/: Bundled helper tools and scripts (stackcollapse-perf, tsc, perf-archive).
• scripts/: Pre- and post-processing scripts (dependency extraction, license checks).
• docs/, README.md: Usage guides and examples.
• Makefile / Dockerfile: Build orchestration and containerization.
README for additional insights
• Six primary commands, each invoking distinct data-collection and rendering flows.
• Supports local and remote targets (via SSH).
• Integrates with Linux perf_events, sysctl, external binaries (stress-ng, fio, MLC, turbostat, avx-turbo).
• Offers a live “Prometheus” endpoint for integration with monitoring systems.
a. CLI Frontend (perfspect binary)
• Subcommands dispatcher (root.go)
• Parses flags (cmd/config, cmd/metrics, etc.)
b. Command Handlers
• metrics, report, telemetry, flame, lock, config modules
c. Core Libraries (internal/*)
• Target abstraction: local_target & remote_target (SSH, credentials, sudo)
• Data collection utilities: common, script (invoking perf, stress-ng, fio, MLC)
• Progress feedback: progress/multispinner
• Reporting engine: report/render_*.go, table_helpers, JSON/HTML/text exporters
d. Resources
• cmd/metrics/resources: event definitions, JSON metric schemas, HTML templates
e. External Dependencies
• OS interfaces: perf_event_open, sysfs, sysctl, syslog
• External binaries: stress-ng, fio, turbostat, MLC, avx-turbo, tsc
• Prometheus HTTP server (metrics_server.go)
f. Outputs
• Filesystem: HTML, CSV, JSON, text reports under output directory
• STDOUT: “live” CSV or text streams
• Network: Prometheus metrics endpoint (HTTP)
• Logs: perfspect.log or syslog
Relationships & data flow
• User invokes perfspect → Command parser → Specific handler
• Handler → internal/target (decide local vs remote) → Data collection layer (perf/syscalls or external tool invocation)
• Collected raw data → internal/report or internal/script for parsing/aggregation → rendering layer
• Renderers → write report files + optionally stream to STDOUT or HTTP endpoint → user/monitoring systems
Architectural patterns & design principles
• Command Pattern (one package per subcommand under cmd/)
• Layered architecture: CLI layer → Application logic layer → Data-collection layer → Rendering layer
• Abstraction of target (local vs remote) isolates SSH details from collection logic
• Resource-driven rendering (HTML templates + JSON schemas) supports extensibility
• Modular design allows adding new commands, renderers, or data sources
Technologies & frameworks
• Go modules (go.mod/go.sum)
• Docker (builder/build.Dockerfile) for reproducible builds
• CI/CD workflows (.github/workflows) for build, test, CodeQL
• Semgrep/staticcheck for static analysis
• External binaries scripted under tools/ and scripts/
Detail
• Resource directories (cmd/metrics/resources) to show templating
• Target abstraction feeding into all data-collection commands
• Optional paths (live mode → STDOUT, Prometheus mode → HTTP)