# prometheus/pushgateway architecture

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

- Interactive diagram: https://gitdiagram.com/prometheus/pushgateway
- Repository: https://github.com/prometheus/pushgateway

## Overview

##### Project type and purpose
- This is a single‐binary, monolithic HTTP service written in Go.
- Purpose: Accept Prometheus‐style metric “pushes” over HTTP, cache them (optionally persist), and expose them back for Prometheus to scrape.

##### File structure
- Top-level:
- main.go – starts HTTP server and routing
- api/v1 – JSON query & admin API handlers
- handler – HTTP endpoints under `/metrics/...` and `/api/...` for push, delete, status, wipe, metrics, etc.
- storage – in-memory metric store with optional file persistence
- asset & resources – embedded VFS assets and static web UI (HTML/CSS/JS)
- histogram – helpers for Prometheus histogram models
- testutil – testing helpers
- Config/build: Dockerfile, Makefile, .circleci, promu.yml for release builds
- README describes flags, usage, TLS/basic‐auth via external web.config

##### README for architecture cues
- Explains HTTP interface (push endpoints, admin/query API, management API)
- Mentions embedded static UI served under root (`/`)
- Talks about Prometheus client_golang for internal metrics, and optional persistence

##### Main components
a. Pushgateway HTTP Server
- Uses Go net/http + mux
- Config: flags (--web.listen-address, --persistence.file, TLS/auth)
b. HTTP Handlers
- Push handlers: POST/PUT `/metrics/job/...` → parse text or protobuf → update Storage
- Delete handler: DELETE `/metrics/job/...` → modify Storage
- Admin API: PUT `/api/v1/admin/wipe` → clear Storage
- Query API: GET `/api/v1/status`, `/api/v1/metrics` → read from Storage + build_info from Go client
- Management: `/-/healthy`, `/-/ready`, `/-/quit`
- Static UI handler: serves embedded or on‐disk assets from `resources/static` via Asset VFS layer
c. Storage Layer
- In‐memory map keyed by grouping labels
- Optional persistence module writes/reads to disk (`--persistence.file`)
- Ensures consistency checks on push
d. Internal Metrics Registry
- Exposes Prometheus Go client metrics (process_, go_, promhttp_, pushgateway_* metrics) on `/metrics`
- Augments pushed metrics with `push_time_seconds` and `push_failure_time_seconds`
e. Prometheus Scraper (external)
- Regularly scrapes `/metrics` on Pushgateway

##### Relationships and interactions
- Client libraries or curl → HTTP Pushgateway server (POST, PUT, DELETE) → Handlers → Storage
- Admin/Query clients → HTTP server → Handlers → Storage or internal state
- HTTP server → Internal Prometheus registry → `/metrics` endpoint
- Persistence module ↔ Storage (periodic serialize, load at startup)
- External Prometheus → Scrape `/metrics` → ingest pushed metrics + Pushgateway’s own metrics

##### Architectural patterns/design principles
- Layered architecture:
- Presentation/API Layer (HTTP handlers)
- Business logic (parsing, consistency checks)
- Storage abstraction (interface + disk store implementation)
- Single‐binary, dependency‐injection via flags & interfaces
- VFS embedding for static assets (asset package + go:generate)
- Use of Prometheus client library for internal metrics

##### Technologies, frameworks, libraries
- Go 1.x, net/http, gorilla/mux (or built‐in router)
- Prometheus client_golang
- go:embed / vfsdata for assets (asset package)
- Docker for containerization
- Makefile/promu for builds and release artifacts
- CircleCI, GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        PUSHERS["Batch/Jobs (Pushers)"]:::external
        PROM_SCRAPER["Prometheus Scraper"]:::external
        ADMIN_CLIENT["Admin/Query Clients"]:::external
    end

    %% HTTP Server Entry
    MAIN["Pushgateway HTTP Server"]:::server
    click MAIN "https://github.com/prometheus/pushgateway/blob/master/main.go"

    %% API / Handlers Layer
    subgraph "API / Handlers Layer"
        direction TB
        subgraph "Push/Delete Handlers" 
            direction TB
            PUSH_HANDLER["POST/PUT /metrics/job/..."]:::api
            click PUSH_HANDLER "https://github.com/prometheus/pushgateway/blob/master/handler/push.go"
            DELETE_HANDLER["DELETE /metrics/job/..."]:::api
            click DELETE_HANDLER "https://github.com/prometheus/pushgateway/blob/master/handler/delete.go"
        end
        subgraph "Admin & Wipe Handlers"
            direction TB
            WIPE_HANDLER["PUT /api/v1/admin/wipe"]:::api
            click WIPE_HANDLER "https://github.com/prometheus/pushgateway/blob/master/handler/wipe.go"
            API_V1["JSON API /api/v1/status & /metrics"]:::api
            click API_V1 "https://github.com/prometheus/pushgateway/blob/master/api/v1/api.go"
        end
        subgraph "Status & Management Handlers"
            direction TB
            STATUS_HANDLER["GET /api/v1/status"]:::api
            click STATUS_HANDLER "https://github.com/prometheus/pushgateway/blob/master/handler/status.go"
            MISC_HANDLER["/-/healthy, /-/ready, /-/quit"]:::api
            click MISC_HANDLER "https://github.com/prometheus/pushgateway/blob/master/handler/misc.go"
        end
        SCRAPE_HANDLER["GET /metrics (Prom internal)"]:::api
        click SCRAPE_HANDLER "https://github.com/prometheus/pushgateway/blob/master/handler/metrics.go"
        UI_HANDLER["Static UI Handler /"]:::api
        click UI_HANDLER "https://github.com/prometheus/pushgateway/blob/master/asset/asset.go"
    end

    %% Internal Metrics Registry
    REGISTRY["Prometheus Client Registry"]:::metrics
    click REGISTRY "https://github.com/prometheus/pushgateway/blob/master/histogram/prometheus_model.go"

    %% Storage & Persistence Layer
    subgraph "Storage Layer"
        direction TB
        STORAGE_IFACE["Storage Interface"]:::storage
        click STORAGE_IFACE "https://github.com/prometheus/pushgateway/blob/master/storage/interface.go"
        INMEMORY_STORE["In-Memory Store"]:::storage
        DISK_STORE["Disk Persistence"]:::persistence
        click DISK_STORE "https://github.com/prometheus/pushgateway/blob/master/storage/diskmetricstore.go"
    end

    %% Static Assets
    subgraph "Static Assets"
        direction TB
        VFS_ASSET["VFS Asset Layer"]:::static
        click VFS_ASSET "https://github.com/prometheus/pushgateway/blob/master/asset/assets_vfsdata.go"
        click VFS_ASSET "https://github.com/prometheus/pushgateway/blob/master/asset/asset_generate.go"
        STATIC_RES["resources/static/"]:::static
        click STATIC_RES "https://github.com/prometheus/pushgateway/tree/master/resources/static/"
        TEMPLATE["resources/template.html"]:::static
        click TEMPLATE "https://github.com/prometheus/pushgateway/blob/master/resources/template.html"
    end

    %% Test & Build
    subgraph "Testing & CI/CD"
        direction TB
        TESTUTIL["Test Utilities"]:::other
        click TESTUTIL "https://github.com/prometheus/pushgateway/blob/master/testutil/metric_families.go"
        DOCKER["Dockerfile"]:::other
        MAKE["Makefile & Makefile.common"]:::other
        CIRCLECI[".circleci/config.yml"]:::other
        PROMU["promu.yml"]:::other
    end

    %% Data Flows
    PUSHERS -->|"push metrics"| PUSH_HANDLER
    DELETE_HANDLER -->|"delete metrics"| INMEMORY_STORE
    PUSH_HANDLER -->|"store metrics"| INMEMORY_STORE
    WIPE_HANDLER -->|"wipe storage"| INMEMORY_STORE
    API_V1 -->|"query status/metrics"| INMEMORY_STORE
    STATUS_HANDLER -->|"status info"| INMEMORY_STORE
    MISC_HANDLER -->|"lifecycle commands"| MAIN
    UI_HANDLER -->|"/ static assets"| VFS_ASSET
    VFS_ASSET -->|"serve files"| MAIN

    INMEMORY_STORE -->|"serialize/deserialize"| DISK_STORE
    MAIN -->|"/metrics endpoint"| REGISTRY
    REGISTRY -->|"gather stored metrics"| INMEMORY_STORE
    PROM_SCRAPER -->|"scrape metrics"| SCRAPE_HANDLER

    %% Connections
    MAIN --> API_V1
    MAIN --> PUSH_HANDLER
    MAIN --> DELETE_HANDLER
    MAIN --> WIPE_HANDLER
    MAIN --> STATUS_HANDLER
    MAIN --> MISC_HANDLER
    MAIN --> SCRAPE_HANDLER
    MAIN --> UI_HANDLER

    %% Styles
    classDef external fill:#E8EAF6,stroke:#3F51B5,color:#1A237E
    classDef server fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef api fill:#BBDEFB,stroke:#2196F3,color:#0D47A1
    classDef storage fill:#DCEDC8,stroke:#8BC34A,color:#33691E
    classDef persistence fill:#FFF9C4,stroke:#FBC02D,color:#F57F17
    classDef metrics fill:#FFCCBC,stroke:#FF5722,color:#BF360C
    classDef static fill:#ECEFF1,stroke:#90A4AE,color:#37474F
    classDef other fill:#F3E5F5,stroke:#AB47BC,color:#4A148C
```
