# avamingli/whpg_plan_tree architecture

> Architecture diagram of the GitHub repository avamingli/whpg_plan_tree, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avamingli/whpg_plan_tree
- Repository: https://github.com/avamingli/whpg_plan_tree

## Overview

whpg_plan_tree is a WarehousePG/GPDB extension for capturing the executing query’s actual plan tree and exposing it through SQL. At query start, the metrics hook triggers capture into a shared-memory pool; SQL consumers can read that plan and, where the kernel library is available, join it with live per-node counters. pg_dash’s Watch feature is a documented consumer. The C excerpt confirms capture and shared-memory responsibilities; SQL and integration links are based on README statements, not inspected SQL definitions.

Main entry points: [`whpg_plan_tree--1.0.0.sql`](https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree--1.0.0.sql) (Plan Detail), [`whpg_plan_tree.c`](https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree.c) (Metrics Hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Plan Capture"]
  node_metrics_hook["Metrics Hook<br/>[whpg_plan_tree.c]"]
  node_capture_logic["Plan Capture<br/>[whpg_plan_tree.c]"]
  node_plan_pool[("Plan Pool<br/>[whpg_plan_tree.c]")]
end

subgraph group_sql["SQL Interface"]
  node_plan_detail["Plan Detail"]
  node_instrument_detail["Instrument Detail"]
end

subgraph group_integrations["Monitoring Integrations"]
  node_metrics_ring[("Metrics Ring")]
  node_pg_dash["pg_dash Watch"]
end

node_query(("Running Query"))
node_consumer(("SQL Consumer"))

node_query -->|"starts query"| node_metrics_hook
node_metrics_hook -->|"triggers capture"| node_capture_logic
node_capture_logic -->|"writes plan"| node_plan_pool
node_plan_pool -->|"supplies rows"| node_plan_detail
node_metrics_ring -->|"supplies counters"| node_instrument_detail
node_consumer -->|"queries"| node_plan_detail
node_consumer -->|"queries"| node_instrument_detail
node_pg_dash -->|"reads plan"| node_plan_detail
node_pg_dash -->|"joins counters"| node_instrument_detail

click node_metrics_hook "https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree.c"
click node_capture_logic "https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree.c"
click node_plan_pool "https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree.c"
click node_plan_detail "https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree--1.0.0.sql"
click node_instrument_detail "https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree--1.0.0.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_metrics_hook,node_capture_logic,node_plan_pool toneBlue
class node_plan_detail,node_instrument_detail toneAmber
class node_metrics_ring,node_pg_dash toneMint
class node_query,node_consumer toneIndigo
```

## Components

### Plan Capture

- [Metrics Hook](https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree.c): `whpg_plan_tree.c`
- [Plan Capture](https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree.c): `whpg_plan_tree.c`
- [Plan Pool](https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree.c): `whpg_plan_tree.c`

### SQL Interface

- [Plan Detail](https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree--1.0.0.sql): `whpg_plan_tree--1.0.0.sql`
- [Instrument Detail](https://github.com/avamingli/whpg_plan_tree/blob/main/whpg_plan_tree--1.0.0.sql): `whpg_plan_tree--1.0.0.sql`

### Monitoring Integrations

- **Metrics Ring**
- **pg_dash Watch**

### Other components

- **Running Query**
- **SQL Consumer**

## Connections

- Running Query → Metrics Hook: starts query (evidence: `README.md`)
- Metrics Hook → Plan Capture: triggers capture (evidence: `README.md`)
- Plan Capture → Plan Pool: writes plan (evidence: `README.md`)
- Plan Pool → Plan Detail: supplies rows (evidence: `README.md`)
- Metrics Ring → Instrument Detail: supplies counters (evidence: `README.md`)
- SQL Consumer → Plan Detail: queries (evidence: `README.md`)
- SQL Consumer → Instrument Detail: queries (evidence: `README.md`)
- pg_dash Watch → Plan Detail: reads plan (evidence: `README.md`)
- pg_dash Watch → Instrument Detail: joins counters (evidence: `README.md`)
