From 6208e4d532248e6ee9d4870ddfb3e39a73cac56b Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 20:43:57 +0000 Subject: [PATCH 1/8] docs: refresh README architecture diagram to cover dynamic profiling The legacy `system_overview.png` only depicts the one-way continuous data plane (agent -> backend -> S3 -> indexer -> ClickHouse) and predates the dynamic profiling work. Replace the System Overview section with a Mermaid diagram that captures both: - Continuous profiling data plane (existing). - Dynamic profiling control plane: heartbeat protocol, ProfilingRequests / ProfilingCommands / ProfilingExecutions, agent two-slot architecture (ContinuousProfilerSlot + AdhocProfilerSlot) with CommandManager priority queue, and optional Intel(R) PerfSpect HW metrics path. Also expands the component list with the new control-plane endpoints and links out to heartbeat_doc/ for full details. Marks the old PNG as legacy rather than deleting it. Co-authored-by: Cursor --- README.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 116 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 3d6e6ec9..9d3ac093 100644 --- a/README.md +++ b/README.md @@ -29,17 +29,120 @@ featuring advanced flamegraph analysis tools. ## System Overview -![system_overview.png](system_overview.png) -The Continuous Profiler is structured around several key microservices, -each playing a vital role in its functionality: -- `src/gprofiler/backend` - This is the web application backend. It exposes all APIs to the frontend or API users and is responsible for collecting data from agents. -- `src/gprofiler/frontend` - The User Interface of Continuous Profiler, facilitating interaction with the backend. -- `src/gprofiler_indexer` - This service is tasked with collecting raw profiling data from S3 storage and indexing it for ClickHouse, a database management system. -- `src/gprofiler_flamedb_rest` - Handles communication with ClickHouse for the purpose of constructing flamegraphs. -- `src/gprofiler_logging` - Dedicated to collecting logs from agents, ensuring a comprehensive logging system. +The Continuous Profiler Performance Studio supports **two profiling modes** that share the +same backend services and storage layer: + +1. **Continuous profiling (data plane)** — Agents periodically upload profile data which is + indexed into ClickHouse and visualized as flame graphs. +2. **Dynamic profiling (control plane)** — Operators trigger ad-hoc / on-demand profiling + sessions from the UI; agents fetch start / stop commands via a heartbeat protocol and can + optionally collect Intel® PerfSpect hardware metrics. See + [`heartbeat_doc/README_HEARTBEAT.md`](heartbeat_doc/README_HEARTBEAT.md) and + [`heartbeat_doc/PERFSPECT_DYNAMIC_PROFILING.md`](heartbeat_doc/PERFSPECT_DYNAMIC_PROFILING.md) + for details. + +### Architecture diagram + +```mermaid +flowchart TB + classDef agent fill:#eef4ff,stroke:#4c6ef5,color:#1a2740 + classDef backend fill:#ede9fe,stroke:#7c3aed,color:#1a2740 + classDef ui fill:#fef3c7,stroke:#d97706,color:#1a2740 + classDef store fill:#f1f5f9,stroke:#475569,color:#1a2740 + classDef aws fill:#fff7ed,stroke:#ea580c,color:#1a2740 + + subgraph AGENT["gProfiler Agent (host)"] + direction TB + HB["Heartbeat loop
POST /api/metrics/heartbeat"] + CMQ["CommandManager
(priority queue:
stop > ad-hoc > continuous)"] + CS["ContinuousProfilerSlot"] + AS["AdhocProfilerSlot"] + PSI["PerfSpect installer
(HW metrics, optional)"] + LOG["Agent logs"] + HB --> CMQ + CMQ --> CS + CMQ --> AS + CS -. enable_perfspect .-> PSI + AS -. enable_perfspect .-> PSI + end + class AGENT,HB,CMQ,CS,AS,PSI,LOG agent + + subgraph UI["Frontend UI (src/gprofiler/frontend)"] + FG["Flame graph & search views"] + CTRL["Dynamic profiling console
Start / Stop, PIDs,
PerfSpect HW metrics"] + end + class UI,FG,CTRL ui + + subgraph BE["Performance Studio Backend"] + WEBAPP["webapp / backend (FastAPI)
src/gprofiler/backend
• /api/metrics/profile_request[/bulk]
• /api/metrics/heartbeat
• /api/metrics/command_completion
• PMU + capacity validation
• Slack notifications"] + LOGSVC["agents-logs-backend
src/gprofiler_logging"] + IDX["gprofiler_indexer"] + REST["gprofiler_flamedb_rest"] + end + class BE,WEBAPP,LOGSVC,IDX,REST backend + + PG[("PostgreSQL
HostHeartbeats
ProfilingRequests
ProfilingCommands
ProfilingExecutions
service metadata")] + CH[("ClickHouse
flamedb")] + S3[["AWS S3
(profile data + adhoc)"]] + SQS[["AWS SQS
(indexer queue)"]] + class PG,CH store + class S3,SQS aws + + %% --- Continuous data plane --- + CS -- "upload profile" --> WEBAPP + AS -- "upload adhoc flamegraph" --> WEBAPP + WEBAPP -- "store raw" --> S3 + WEBAPP -- "enqueue index task" --> SQS + SQS -- "trigger" --> IDX + IDX -- "read raw" --> S3 + IDX -- "write samples" --> CH + REST -- "query" --> CH + WEBAPP -- "query flames" --> REST + + %% --- Logs --- + LOG -- "POST agent logs" --> LOGSVC + LOGSVC --> PG + + %% --- Metadata --- + WEBAPP <--> PG + + %% --- Dynamic profiling control plane --- + HB <==> |"heartbeat ↑
command ↓"| WEBAPP + CTRL -- "create profiling request" --> WEBAPP + + %% --- UI queries --- + FG -- "queries" --> WEBAPP +``` -This architecture allows for efficient handling and analysis of profiling data, providing users with an intuitive and powerful tool for performance analysis. +### Components + +The Performance Studio is structured around several key microservices: + +- `src/gprofiler/backend` — Web application backend (FastAPI). Exposes APIs to the frontend + and API users, ingests continuous profile data from agents, and hosts the **dynamic + profiling control plane** (`/api/metrics/heartbeat`, `/api/metrics/profile_request`, + `/api/metrics/profile_request/bulk`, `/api/metrics/command_completion`, + `/api/metrics/profiling/host_status`). +- `src/gprofiler/frontend` — Web UI. Renders flame graphs and provides the dynamic + profiling console (Start / Stop, target hosts and PIDs, PerfSpect hardware-metrics + toggle). +- `src/gprofiler_indexer` — Reads raw profiling data from S3 (triggered via SQS) and + indexes it into ClickHouse. +- `src/gprofiler_flamedb_rest` — REST layer that the backend uses to query flame graphs + out of ClickHouse. +- `src/gprofiler_logging` (`agents-logs-backend`) — Collects logs from agents. + +The **gProfiler agent** itself (see [intel/gprofiler](https://github.com/intel/gprofiler)) +runs on each profiled host and contributes two roles: + +- **Data plane** — Continuously uploads profile data to the backend. +- **Control plane** — When started with `--enable-heartbeat-server`, runs a heartbeat + loop that fetches start / stop commands from the backend and dispatches them through a + `CommandManager` priority queue into one of two execution slots + (`ContinuousProfilerSlot`, `AdhocProfilerSlot`) which can run in parallel for + non-overlapping profiler types. Optionally bootstraps Intel® PerfSpect for hardware + metrics collection. ### External Dependencies: AWS Services The Continuous Profiler incorporates specific AWS services as essential components. @@ -52,6 +155,10 @@ These dependencies are: You are welcome to replace those services with other similar which implement the same API, like Minio for S3 and RabbitMQ for SQS. +> **Note:** The legacy `system_overview.png` diagram only depicted the continuous data +> plane and predates dynamic profiling. The Mermaid diagram above is the current source of +> truth. + ## Usage ### Pre-requisites From 678cb673236515d9beeff204c135b170e47203dd Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 20:50:02 +0000 Subject: [PATCH 2/8] docs: simplify agent block in architecture diagram for blog use Co-authored-by: Cursor --- README.md | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9d3ac093..b13d1e23 100644 --- a/README.md +++ b/README.md @@ -52,21 +52,8 @@ flowchart TB classDef store fill:#f1f5f9,stroke:#475569,color:#1a2740 classDef aws fill:#fff7ed,stroke:#ea580c,color:#1a2740 - subgraph AGENT["gProfiler Agent (host)"] - direction TB - HB["Heartbeat loop
POST /api/metrics/heartbeat"] - CMQ["CommandManager
(priority queue:
stop > ad-hoc > continuous)"] - CS["ContinuousProfilerSlot"] - AS["AdhocProfilerSlot"] - PSI["PerfSpect installer
(HW metrics, optional)"] - LOG["Agent logs"] - HB --> CMQ - CMQ --> CS - CMQ --> AS - CS -. enable_perfspect .-> PSI - AS -. enable_perfspect .-> PSI - end - class AGENT,HB,CMQ,CS,AS,PSI,LOG agent + AGENT["gProfiler Agent (host)
• continuous + ad-hoc profiling
• optional Intel® PerfSpect HW metrics"] + class AGENT agent subgraph UI["Frontend UI (src/gprofiler/frontend)"] FG["Flame graph & search views"] @@ -90,8 +77,7 @@ flowchart TB class S3,SQS aws %% --- Continuous data plane --- - CS -- "upload profile" --> WEBAPP - AS -- "upload adhoc flamegraph" --> WEBAPP + AGENT -- "upload profile / adhoc flamegraph" --> WEBAPP WEBAPP -- "store raw" --> S3 WEBAPP -- "enqueue index task" --> SQS SQS -- "trigger" --> IDX @@ -101,14 +87,14 @@ flowchart TB WEBAPP -- "query flames" --> REST %% --- Logs --- - LOG -- "POST agent logs" --> LOGSVC + AGENT -- "POST agent logs" --> LOGSVC LOGSVC --> PG %% --- Metadata --- WEBAPP <--> PG %% --- Dynamic profiling control plane --- - HB <==> |"heartbeat ↑
command ↓"| WEBAPP + AGENT <==> |"heartbeat ↑
command ↓"| WEBAPP CTRL -- "create profiling request" --> WEBAPP %% --- UI queries --- From ea35502f182570c73c35736dfd736ecb4ac357d8 Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 20:58:07 +0000 Subject: [PATCH 3/8] docs: restyle architecture diagram (grey canvas, Figma-y cards, dashed control plane) Co-authored-by: Cursor --- README.md | 94 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 54 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index b13d1e23..2a110208 100644 --- a/README.md +++ b/README.md @@ -44,63 +44,77 @@ same backend services and storage layer: ### Architecture diagram +> The diagram is written in Mermaid so it stays diff-able. To export it as a PNG / SVG +> for slides or a blog post, paste the source into [mermaid.live](https://mermaid.live) +> and pick your preferred background — the theme below is tuned for a light grey canvas. + ```mermaid +%%{init: { + 'theme': 'base', + 'themeVariables': { + 'background': '#f3f4f6', + 'primaryColor': '#ffffff', + 'primaryBorderColor': '#cbd5e1', + 'primaryTextColor': '#0f172a', + 'lineColor': '#64748b', + 'fontFamily': 'Inter, ui-sans-serif, system-ui, sans-serif', + 'fontSize': '14px' + } +}}%% flowchart TB - classDef agent fill:#eef4ff,stroke:#4c6ef5,color:#1a2740 - classDef backend fill:#ede9fe,stroke:#7c3aed,color:#1a2740 - classDef ui fill:#fef3c7,stroke:#d97706,color:#1a2740 - classDef store fill:#f1f5f9,stroke:#475569,color:#1a2740 - classDef aws fill:#fff7ed,stroke:#ea580c,color:#1a2740 - - AGENT["gProfiler Agent (host)
• continuous + ad-hoc profiling
• optional Intel® PerfSpect HW metrics"] - class AGENT agent - - subgraph UI["Frontend UI (src/gprofiler/frontend)"] - FG["Flame graph & search views"] - CTRL["Dynamic profiling console
Start / Stop, PIDs,
PerfSpect HW metrics"] + classDef agent fill:#eaf2ff,stroke:#3b82f6,stroke-width:1.5px,color:#1e293b + classDef ui fill:#fff4d6,stroke:#d97706,stroke-width:1.5px,color:#1e293b + classDef be fill:#ece6ff,stroke:#7c3aed,stroke-width:1.5px,color:#1e293b + classDef store fill:#fde2f3,stroke:#db2777,stroke-width:1.5px,color:#1e293b + classDef aws fill:#ffedd5,stroke:#ea580c,stroke-width:1.5px,color:#1e293b + + AGENT["🖥️ gProfiler Agent (host)
continuous + ad-hoc profiling
+ optional Intel® PerfSpect HW metrics"]:::agent + + subgraph UIBOX["🌐 Frontend UI"] + direction TB + FG["Flame graphs & search"]:::ui + CTRL["Dynamic profiling console
Start / Stop · PIDs · PerfSpect"]:::ui end - class UI,FG,CTRL ui - subgraph BE["Performance Studio Backend"] - WEBAPP["webapp / backend (FastAPI)
src/gprofiler/backend
• /api/metrics/profile_request[/bulk]
• /api/metrics/heartbeat
• /api/metrics/command_completion
• PMU + capacity validation
• Slack notifications"] - LOGSVC["agents-logs-backend
src/gprofiler_logging"] - IDX["gprofiler_indexer"] - REST["gprofiler_flamedb_rest"] + subgraph BEBOX["⚙️ Performance Studio Backend"] + direction TB + WEBAPP["webapp / FastAPI
profile_request · heartbeat
command_completion · host_status"]:::be + LOGSVC["agents-logs-backend"]:::be + IDX["gprofiler_indexer"]:::be + REST["gprofiler_flamedb_rest"]:::be end - class BE,WEBAPP,LOGSVC,IDX,REST backend - PG[("PostgreSQL
HostHeartbeats
ProfilingRequests
ProfilingCommands
ProfilingExecutions
service metadata")] - CH[("ClickHouse
flamedb")] - S3[["AWS S3
(profile data + adhoc)"]] - SQS[["AWS SQS
(indexer queue)"]] - class PG,CH store - class S3,SQS aws + PG[("🗄️ PostgreSQL
HostHeartbeats · ProfilingRequests
ProfilingCommands · service metadata")]:::store + CH[("🗄️ ClickHouse — flamedb")]:::store + S3[["☁️ AWS S3"]]:::aws + SQS[["☁️ AWS SQS"]]:::aws + + style UIBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a + style BEBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a - %% --- Continuous data plane --- - AGENT -- "upload profile / adhoc flamegraph" --> WEBAPP + %% --- data plane (solid) --- + AGENT -- "upload profile / adhoc" --> WEBAPP WEBAPP -- "store raw" --> S3 - WEBAPP -- "enqueue index task" --> SQS + WEBAPP -- "enqueue" --> SQS SQS -- "trigger" --> IDX IDX -- "read raw" --> S3 IDX -- "write samples" --> CH + WEBAPP <--> REST REST -- "query" --> CH - WEBAPP -- "query flames" --> REST - - %% --- Logs --- - AGENT -- "POST agent logs" --> LOGSVC + AGENT -- "agent logs" --> LOGSVC LOGSVC --> PG - - %% --- Metadata --- WEBAPP <--> PG - - %% --- Dynamic profiling control plane --- - AGENT <==> |"heartbeat ↑
command ↓"| WEBAPP - CTRL -- "create profiling request" --> WEBAPP - - %% --- UI queries --- FG -- "queries" --> WEBAPP + + %% --- control plane (dashed) --- + AGENT <-. "heartbeat ↑ / command ↓" .-> WEBAPP + CTRL -. "profiling request" .-> WEBAPP ``` +**Legend.** Solid arrows are the continuous **data plane** (profile upload → S3 → SQS → +indexer → ClickHouse → flame graphs). Dashed arrows are the dynamic **control plane** +(UI creates a profiling request; agent fetches start / stop commands via heartbeat). + ### Components The Performance Studio is structured around several key microservices: From 652b0e91e38c7544954af4ff2ed21c81d9dae93c Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 21:04:41 +0000 Subject: [PATCH 4/8] docs: fix clipped AWS S3/SQS labels in architecture diagram Co-authored-by: Cursor --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2a110208..2c8417ae 100644 --- a/README.md +++ b/README.md @@ -86,8 +86,8 @@ flowchart TB PG[("🗄️ PostgreSQL
HostHeartbeats · ProfilingRequests
ProfilingCommands · service metadata")]:::store CH[("🗄️ ClickHouse — flamedb")]:::store - S3[["☁️ AWS S3"]]:::aws - SQS[["☁️ AWS SQS"]]:::aws + S3["☁️ AWS S3
profile data + adhoc"]:::aws + SQS["☁️ AWS SQS
indexer queue"]:::aws style UIBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a style BEBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a From cc1e9cdfd9d9dc1abd341a6daeda6abf1d39139a Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 21:18:18 +0000 Subject: [PATCH 5/8] docs: tweak diagram theme (grey #e5e7eb, rounded corners) and prose Co-authored-by: Cursor --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2c8417ae..d5dc6309 100644 --- a/README.md +++ b/README.md @@ -45,20 +45,21 @@ same backend services and storage layer: ### Architecture diagram > The diagram is written in Mermaid so it stays diff-able. To export it as a PNG / SVG -> for slides or a blog post, paste the source into [mermaid.live](https://mermaid.live) +> for slides or docs, paste the source into [mermaid.live](https://mermaid.live) > and pick your preferred background — the theme below is tuned for a light grey canvas. ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { - 'background': '#f3f4f6', + 'background': '#e5e7eb', 'primaryColor': '#ffffff', 'primaryBorderColor': '#cbd5e1', 'primaryTextColor': '#0f172a', 'lineColor': '#64748b', 'fontFamily': 'Inter, ui-sans-serif, system-ui, sans-serif', - 'fontSize': '14px' + 'fontSize': '14px', + 'borderRadius': '8px' } }}%% flowchart TB From 742db30962eb7ca28197ed0f8d852961a05f2da1 Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 21:23:02 +0000 Subject: [PATCH 6/8] docs: render grey canvas + rounded corners on GitHub via outer subgraph and rx/ry Co-authored-by: Cursor --- README.md | 66 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index d5dc6309..719a4551 100644 --- a/README.md +++ b/README.md @@ -44,54 +44,60 @@ same backend services and storage layer: ### Architecture diagram -> The diagram is written in Mermaid so it stays diff-able. To export it as a PNG / SVG -> for slides or docs, paste the source into [mermaid.live](https://mermaid.live) -> and pick your preferred background — the theme below is tuned for a light grey canvas. +> The diagram is written in Mermaid so it stays diff-able. The outer grey card and +> rounded corners below render natively on GitHub via `style` directives and `rx`/`ry` +> on each `classDef`. For a clean PNG / SVG export for slides or docs, paste the source +> into [mermaid.live](https://mermaid.live) and use its **Background** picker (Mermaid +> itself doesn't expose a `background` theme variable — the SVG is transparent and the +> page CSS shows through). ```mermaid %%{init: { 'theme': 'base', 'themeVariables': { - 'background': '#e5e7eb', 'primaryColor': '#ffffff', 'primaryBorderColor': '#cbd5e1', 'primaryTextColor': '#0f172a', 'lineColor': '#64748b', 'fontFamily': 'Inter, ui-sans-serif, system-ui, sans-serif', - 'fontSize': '14px', - 'borderRadius': '8px' + 'fontSize': '14px' } }}%% flowchart TB - classDef agent fill:#eaf2ff,stroke:#3b82f6,stroke-width:1.5px,color:#1e293b - classDef ui fill:#fff4d6,stroke:#d97706,stroke-width:1.5px,color:#1e293b - classDef be fill:#ece6ff,stroke:#7c3aed,stroke-width:1.5px,color:#1e293b - classDef store fill:#fde2f3,stroke:#db2777,stroke-width:1.5px,color:#1e293b - classDef aws fill:#ffedd5,stroke:#ea580c,stroke-width:1.5px,color:#1e293b + classDef agent fill:#eaf2ff,stroke:#3b82f6,stroke-width:1.5px,color:#1e293b,rx:8,ry:8 + classDef ui fill:#fff4d6,stroke:#d97706,stroke-width:1.5px,color:#1e293b,rx:8,ry:8 + classDef be fill:#ece6ff,stroke:#7c3aed,stroke-width:1.5px,color:#1e293b,rx:8,ry:8 + classDef store fill:#fde2f3,stroke:#db2777,stroke-width:1.5px,color:#1e293b,rx:8,ry:8 + classDef aws fill:#ffedd5,stroke:#ea580c,stroke-width:1.5px,color:#1e293b,rx:8,ry:8 - AGENT["🖥️ gProfiler Agent (host)
continuous + ad-hoc profiling
+ optional Intel® PerfSpect HW metrics"]:::agent - - subgraph UIBOX["🌐 Frontend UI"] + subgraph CANVAS[" "] direction TB - FG["Flame graphs & search"]:::ui - CTRL["Dynamic profiling console
Start / Stop · PIDs · PerfSpect"]:::ui - end - subgraph BEBOX["⚙️ Performance Studio Backend"] - direction TB - WEBAPP["webapp / FastAPI
profile_request · heartbeat
command_completion · host_status"]:::be - LOGSVC["agents-logs-backend"]:::be - IDX["gprofiler_indexer"]:::be - REST["gprofiler_flamedb_rest"]:::be + AGENT["🖥️ gProfiler Agent (host)
continuous + ad-hoc profiling
+ optional Intel® PerfSpect HW metrics"]:::agent + + subgraph UIBOX["🌐 Frontend UI"] + direction TB + FG["Flame graphs & search"]:::ui + CTRL["Dynamic profiling console
Start / Stop · PIDs · PerfSpect"]:::ui + end + + subgraph BEBOX["⚙️ Performance Studio Backend"] + direction TB + WEBAPP["webapp / FastAPI
profile_request · heartbeat
command_completion · host_status"]:::be + LOGSVC["agents-logs-backend"]:::be + IDX["gprofiler_indexer"]:::be + REST["gprofiler_flamedb_rest"]:::be + end + + PG[("🗄️ PostgreSQL
HostHeartbeats · ProfilingRequests
ProfilingCommands · service metadata")]:::store + CH[("🗄️ ClickHouse — flamedb")]:::store + S3["☁️ AWS S3
profile data + adhoc"]:::aws + SQS["☁️ AWS SQS
indexer queue"]:::aws end - PG[("🗄️ PostgreSQL
HostHeartbeats · ProfilingRequests
ProfilingCommands · service metadata")]:::store - CH[("🗄️ ClickHouse — flamedb")]:::store - S3["☁️ AWS S3
profile data + adhoc"]:::aws - SQS["☁️ AWS SQS
indexer queue"]:::aws - - style UIBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a - style BEBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a + style CANVAS fill:#e5e7eb,stroke:#cbd5e1,stroke-width:1px,color:#0f172a + style UIBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a + style BEBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a %% --- data plane (solid) --- AGENT -- "upload profile / adhoc" --> WEBAPP From 9866264979ea451d0b79623b2c0599b5655d8ce3 Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 21:25:25 +0000 Subject: [PATCH 7/8] docs: lighten architecture diagram canvas to slate-100 Co-authored-by: Cursor --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 719a4551..9359a8f3 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ flowchart TB SQS["☁️ AWS SQS
indexer queue"]:::aws end - style CANVAS fill:#e5e7eb,stroke:#cbd5e1,stroke-width:1px,color:#0f172a + style CANVAS fill:#f1f5f9,stroke:#e2e8f0,stroke-width:1px,color:#0f172a style UIBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a style BEBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a From 167aa28d25a254f7c376df6750e59a0caec38180 Mon Sep 17 00:00:00 2001 From: prashantbytesyntax Date: Thu, 4 Jun 2026 21:30:20 +0000 Subject: [PATCH 8/8] docs: drop outer canvas wrap; keep Frontend UI + Backend as standalone light-grey cards Co-authored-by: Cursor --- README.md | 56 ++++++++++++++++++++++++++----------------------------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 9359a8f3..1d470899 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,13 @@ same backend services and storage layer: ### Architecture diagram -> The diagram is written in Mermaid so it stays diff-able. The outer grey card and -> rounded corners below render natively on GitHub via `style` directives and `rx`/`ry` -> on each `classDef`. For a clean PNG / SVG export for slides or docs, paste the source -> into [mermaid.live](https://mermaid.live) and use its **Background** picker (Mermaid -> itself doesn't expose a `background` theme variable — the SVG is transparent and the -> page CSS shows through). +> The diagram is written in Mermaid so it stays diff-able. The light-grey container +> cards (Frontend UI, Performance Studio Backend) and rounded corners below render +> natively on GitHub via `style` directives and `rx`/`ry` on each `classDef`. For a +> clean PNG / SVG export for slides or docs, paste the source into +> [mermaid.live](https://mermaid.live) and use its **Background** picker (Mermaid +> itself doesn't expose a `background` theme variable — the SVG is transparent and +> the page CSS shows through). ```mermaid %%{init: { @@ -70,34 +71,29 @@ flowchart TB classDef store fill:#fde2f3,stroke:#db2777,stroke-width:1.5px,color:#1e293b,rx:8,ry:8 classDef aws fill:#ffedd5,stroke:#ea580c,stroke-width:1.5px,color:#1e293b,rx:8,ry:8 - subgraph CANVAS[" "] + AGENT["🖥️ gProfiler Agent (host)
continuous + ad-hoc profiling
+ optional Intel® PerfSpect HW metrics"]:::agent + + subgraph UIBOX["🌐 Frontend UI"] direction TB + FG["Flame graphs & search"]:::ui + CTRL["Dynamic profiling console
Start / Stop · PIDs · PerfSpect"]:::ui + end - AGENT["🖥️ gProfiler Agent (host)
continuous + ad-hoc profiling
+ optional Intel® PerfSpect HW metrics"]:::agent - - subgraph UIBOX["🌐 Frontend UI"] - direction TB - FG["Flame graphs & search"]:::ui - CTRL["Dynamic profiling console
Start / Stop · PIDs · PerfSpect"]:::ui - end - - subgraph BEBOX["⚙️ Performance Studio Backend"] - direction TB - WEBAPP["webapp / FastAPI
profile_request · heartbeat
command_completion · host_status"]:::be - LOGSVC["agents-logs-backend"]:::be - IDX["gprofiler_indexer"]:::be - REST["gprofiler_flamedb_rest"]:::be - end - - PG[("🗄️ PostgreSQL
HostHeartbeats · ProfilingRequests
ProfilingCommands · service metadata")]:::store - CH[("🗄️ ClickHouse — flamedb")]:::store - S3["☁️ AWS S3
profile data + adhoc"]:::aws - SQS["☁️ AWS SQS
indexer queue"]:::aws + subgraph BEBOX["⚙️ Performance Studio Backend"] + direction TB + WEBAPP["webapp / FastAPI
profile_request · heartbeat
command_completion · host_status"]:::be + LOGSVC["agents-logs-backend"]:::be + IDX["gprofiler_indexer"]:::be + REST["gprofiler_flamedb_rest"]:::be end - style CANVAS fill:#f1f5f9,stroke:#e2e8f0,stroke-width:1px,color:#0f172a - style UIBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a - style BEBOX fill:#fafafa,stroke:#e5e7eb,stroke-width:1px,color:#0f172a + PG[("🗄️ PostgreSQL
HostHeartbeats · ProfilingRequests
ProfilingCommands · service metadata")]:::store + CH[("🗄️ ClickHouse — flamedb")]:::store + S3["☁️ AWS S3
profile data + adhoc"]:::aws + SQS["☁️ AWS SQS
indexer queue"]:::aws + + style UIBOX fill:#f1f5f9,stroke:#e2e8f0,stroke-width:1px,color:#0f172a + style BEBOX fill:#f1f5f9,stroke:#e2e8f0,stroke-width:1px,color:#0f172a %% --- data plane (solid) --- AGENT -- "upload profile / adhoc" --> WEBAPP