# whileone-techsoft/perfspect architecture

> Architecture diagram of the GitHub repository whileone-techsoft/perfspect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whileone-techsoft/perfspect
- Repository: https://github.com/whileone-techsoft/perfspect

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        User["User"]:::external
        CLI["perfspect CLI Dispatcher"]:::internal
        User --> CLI
    end

    %% Commands Layer
    subgraph "Commands"
        direction TB
        Metrics["Metrics Command"]:::internal
        Report["Report Command"]:::internal
        Telemetry["Telemetry Command"]:::internal
        Flame["Flame Command"]:::internal
        Lock["Lock Contention Command"]:::internal
        Config["Config Command"]:::internal
        CLI --> Metrics
        CLI --> Report
        CLI --> Telemetry
        CLI --> Flame
        CLI --> Lock
        CLI --> Config
    end

    %% Resources for Metrics
    subgraph "Metrics Resources" 
        direction TB
        BaseHTML["base.html"]:::internal
        EventsResources["events/..."]:::internal
        MetricsSchema["metrics/..."]:::internal
        Metrics --> BaseHTML
        Metrics --> EventsResources
        Metrics --> MetricsSchema
    end

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        Target["Target Abstraction"]:::internal
        Common["Common Utilities"]:::internal
        Script["Script Invocation Layer"]:::internal
        Progress["Progress Feedback"]:::internal
        Reporter["Reporting Engine"]:::internal
        Metrics --> Target
        Report --> Target
        Telemetry --> Target
        Flame --> Target
        Lock --> Target
        Config --> Target
        Metrics --> Common
        Metrics --> Script
        Metrics --> Progress
        Metrics --> Reporter
    end

    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        OS["OS Interfaces"]:::external
        Binaries["External Binaries"]:::external
        SSH["SSH Remote Target"]:::external
        Target --> OS
        Target --> Binaries
        Target --> SSH
    end

    %% Prometheus Server
    PromServer["Prometheus HTTP Endpoint"]:::external
    Metrics --> PromServer

    %% Outputs
    subgraph "Outputs"
        direction TB
        Files["HTML/CSV/JSON/Text Files"]:::output
        Stream["STDOUT Streams"]:::output
        HTTP["HTTP Metrics Endpoint"]:::output
        Logs["Logs (perfspect.log/syslog)"]:::output
        Reporter --> Files
        Reporter --> Stream
        PromServer --> HTTP
        Reporter --> Logs
    end

    %% Build and CI/CD
    subgraph "Build & CI/CD" 
        direction TB
        Builder["Docker Build Scripts"]:::build
        CI["CI Workflows"]:::build
        Make["Makefile/Dockerfile"]:::build
    end

    Builder --> CLI
    CI --> Builder

    %% Click Events
    click CLI "https://github.com/whileone-techsoft/perfspect/blob/main/main.go"
    click CLI "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/root.go"
    click Metrics "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/metrics/metrics.go"
    click Metrics "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/metrics/event_defs.go"
    click Metrics "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/metrics/perf.go"
    click Metrics "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/metrics/process.go"
    click Metrics "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/metrics/print.go"
    click Metrics "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/metrics/metrics_server.go"
    click Report "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/report/report.go"
    click Telemetry "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/telemetry/telemetry.go"
    click Flame "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/flame/flame.go"
    click Lock "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/lock/lock.go"
    click Config "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/config/config.go"
    click Config "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/config/flag.go"
    click Config "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/config/flag_groups.go"
    click Config "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/config/set.go"
    click BaseHTML "https://github.com/whileone-techsoft/perfspect/blob/main/cmd/metrics/resources/base.html"
    click EventsResources "https://github.com/whileone-techsoft/perfspect/tree/main/cmd/metrics/resources/events/"
    click MetricsSchema "https://github.com/whileone-techsoft/perfspect/tree/main/cmd/metrics/resources/metrics/"
    click Target "https://github.com/whileone-techsoft/perfspect/blob/main/internal/target/target.go"
    click Target "https://github.com/whileone-techsoft/perfspect/blob/main/internal/target/local_target.go"
    click Target "https://github.com/whileone-techsoft/perfspect/blob/main/internal/target/remote_target.go"
    click Target "https://github.com/whileone-techsoft/perfspect/blob/main/internal/target/helpers.go"
    click Common "https://github.com/whileone-techsoft/perfspect/blob/main/internal/common/common.go"
    click Common "https://github.com/whileone-techsoft/perfspect/blob/main/internal/common/targets.go"
    click Script "https://github.com/whileone-techsoft/perfspect/blob/main/internal/script/script.go"
    click Script "https://github.com/whileone-techsoft/perfspect/blob/main/internal/script/script_defs.go"
    click Progress "https://github.com/whileone-techsoft/perfspect/blob/main/internal/progress/multispinner.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/report.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/render_html.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/render_html_flamegraph.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/render_json.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/render_text.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/render_excel.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/render_raw.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/table_helpers.go"
    click Reporter "https://github.com/whileone-techsoft/perfspect/blob/main/internal/report/table.go"
    click Builder "https://github.com/whileone-techsoft/perfspect/blob/main/builder/build.Dockerfile"
    click Builder "https://github.com/whileone-techsoft/perfspect/blob/main/builder/build.sh"
    click CI "https://github.com/whileone-techsoft/perfspect/blob/main/.github/workflows/build-test.yml"
    click CI "https://github.com/whileone-techsoft/perfspect/blob/main/.github/workflows/codeql.yml"
    click Make "https://github.com/whileone-techsoft/perfspect/tree/main/Makefile"
    click Make "https://github.com/whileone-techsoft/perfspect/tree/main/Dockerfile"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef output fill:#fff3cd,stroke:#856404,color:#856404
    classDef build fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-dasharray: 5 5
```
