# rapidloop/pgmetrics architecture

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

- Interactive diagram: https://gitdiagram.com/rapidloop/pgmetrics
- Repository: https://github.com/rapidloop/pgmetrics

## Overview

##### Project type and purpose
- Project type: A command-line monitoring tool written in Go.
- Purpose: Connects to a running PostgreSQL server (and related systems) to collect statistics and metrics, then displays or exports them (e.g., to CSV) for troubleshooting, monitoring, and automation.

##### File structure
- cmd/pgmetrics: The CLI entrypoint and subcommands (main.go, csv.go, report.go).
- collector/: A set of modules (“plugins”) that each implement data collection from different sources:
- AWS/Azure cloud metadata or managed Postgres services
- Citus (sharded Postgres)
- Pgpool
- OS-level system metrics (Linux, Windows, Darwin, FreeBSD)
- Generic PostgreSQL metrics (collect.go)
- model.go: Defines in-memory data structures for metrics.
- .goreleaser.yml, Dockerfile: Build and packaging configurations.
- go.mod/go.sum: Dependency management.
- README.md: High-level description.

##### README for additional insights
- External docs (pgmetrics.io) describe use cases: performance tuning, automation, alerts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and Main Flow
    User["User"]:::external
    CLI["CLI Frontend\n(main.go)"]:::internal
    Framework["Collector Framework\n(collect.go)"]:::internal

    %% Collector Modules
    subgraph "Collector Modules"
        AWS["AWS Collector"]:::internal
        Azure["Azure Collector"]:::internal
        Citus["Citus Collector"]:::internal
        Pgpool["Pgpool Collector"]:::internal
        Postgres["Postgres Collector"]:::internal
        subgraph "OS System Collectors"
            Linux["Linux Sys Collector"]:::internal
            Windows["Windows Sys Collector"]:::internal
            Darwin["Darwin Sys Collector"]:::internal
            FreeBSD["FreeBSD Sys Collector"]:::internal
        end
        Logging["Collector Logging\n(log.go)"]:::internal
    end

    %% Data Model
    Model["Data Model\n(model.go)"]:::data

    %% Reporter Layer
    subgraph "Reporter Layer"
        Console["Console Reporter\n(report.go)"]:::internal
        CSV["CSV Reporter\n(csv.go)"]:::internal
    end

    %% External Systems
    subgraph "External Systems"
        PostgresDB["PostgreSQL Server"]:::external
        AWSAPI["AWS API"]:::external
        AzureAPI["Azure API"]:::external
        CitusShards["Citus Shards"]:::external
        PgpoolInstance["Pgpool Instance"]:::external
        OSSubsystem["Host OS Metrics"]:::external
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        DockerfileNode["Dockerfile"]:::build
        Goreleaser[".goreleaser.yml"]:::build
        GoMod["go.mod"]:::build
        GoSum["go.sum"]:::build
        README["README.md"]:::docs
    end

    %% Connections
    User -->|"invoke"| CLI
    CLI -->|"initialize"| Framework

    Framework -->|"init AWS"| AWS
    Framework -->|"init Azure"| Azure
    Framework -->|"init Citus"| Citus
    Framework -->|"init Pgpool"| Pgpool
    Framework -->|"init Postgres"| Postgres
    Framework -->|"init Linux"| Linux
    Framework -->|"init Windows"| Windows
    Framework -->|"init Darwin"| Darwin
    Framework -->|"init FreeBSD"| FreeBSD

    AWS -->|"HTTP API call"| AWSAPI
    Azure -->|"HTTP API call"| AzureAPI
    Citus -->|"SQL/API"| CitusShards
    Pgpool -->|"SQL queries"| PgpoolInstance
    Postgres -->|"SQL queries"| PostgresDB
    Linux -->|"OS syscall"| OSSubsystem
    Windows -->|"OS syscall"| OSSubsystem
    Darwin -->|"OS syscall"| OSSubsystem
    FreeBSD -->|"OS syscall"| OSSubsystem

    AWS -->|metrics| Model
    Azure -->|metrics| Model
    Citus -->|metrics| Model
    Pgpool -->|metrics| Model
    Postgres -->|metrics| Model
    Linux -->|metrics| Model
    Windows -->|metrics| Model
    Darwin -->|metrics| Model
    FreeBSD -->|metrics| Model

    AWS --> Logging
    Azure --> Logging
    Citus --> Logging
    Pgpool --> Logging
    Postgres --> Logging
    Linux --> Logging
    Windows --> Logging
    Darwin --> Logging
    FreeBSD --> Logging

    Model -->|"structured data"| Console
    Model -->|"structured data"| CSV
    Console -->|"stdout"| User
    CSV -->|"file output"| User

    DockerfileNode -->|"build image"| CLI
    Goreleaser -->|"release binary"| CLI
    GoMod -->|"dependencies"| CLI
    GoSum -->|"dependencies"| CLI
    README -->|"documentation"| CLI

    %% Click Events
    click CLI "https://github.com/rapidloop/pgmetrics/blob/master/cmd/pgmetrics/main.go"
    click Console "https://github.com/rapidloop/pgmetrics/blob/master/cmd/pgmetrics/report.go"
    click CSV "https://github.com/rapidloop/pgmetrics/blob/master/cmd/pgmetrics/csv.go"
    click Framework "https://github.com/rapidloop/pgmetrics/blob/master/collector/collect.go"
    click Logging "https://github.com/rapidloop/pgmetrics/blob/master/collector/log.go"
    click AWS "https://github.com/rapidloop/pgmetrics/blob/master/collector/aws.go"
    click Azure "https://github.com/rapidloop/pgmetrics/blob/master/collector/azure.go"
    click Citus "https://github.com/rapidloop/pgmetrics/blob/master/collector/citus.go"
    click Pgpool "https://github.com/rapidloop/pgmetrics/blob/master/collector/pgpool.go"
    click Postgres "https://github.com/rapidloop/pgmetrics/blob/master/collector/collect.go"
    click Linux "https://github.com/rapidloop/pgmetrics/blob/master/collector/system_linux.go"
    click Windows "https://github.com/rapidloop/pgmetrics/blob/master/collector/system_windows.go"
    click Darwin "https://github.com/rapidloop/pgmetrics/blob/master/collector/system_darwin.go"
    click FreeBSD "https://github.com/rapidloop/pgmetrics/blob/master/collector/system_freebsd.go"
    click Model "https://github.com/rapidloop/pgmetrics/blob/master/model.go"
    click DockerfileNode "https://github.com/rapidloop/pgmetrics/tree/master/Dockerfile"
    click Goreleaser "https://github.com/rapidloop/pgmetrics/blob/master/.goreleaser.yml"
    click GoMod "https://github.com/rapidloop/pgmetrics/blob/master/go.mod"
    click GoSum "https://github.com/rapidloop/pgmetrics/blob/master/go.sum"
    click README "https://github.com/rapidloop/pgmetrics/blob/master/README.md"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#1E90FF;
    classDef external fill:#90EE90,stroke:#008000;
    classDef data fill:#FFFFE0,stroke:#CCCC00;
    classDef build fill:#D3D3D3,stroke:#696969;
    classDef docs fill:#FFFACD,stroke:#DAA520;
```
