docs: refresh README architecture diagram to cover dynamic profiling#117
Merged
Conversation
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 <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…d control plane) Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…ph and rx/ry Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
…e light-grey cards Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The legacy
system_overview.pngonly depicts the one-way continuous data plane (agent → backend → S3 → indexer → ClickHouse) and predates the dynamic profiling work that has since landed (heartbeat protocol,ProfilingRequests/ProfilingCommands/ProfilingExecutions, two-slot agent, PerfSpect HW metrics — seeheartbeat_doc/).This PR replaces the README's System Overview section with a Mermaid diagram that captures both the continuous data plane and the new dynamic profiling control plane, and expands the component list with the new endpoints. The legacy PNG is left in the repo and called out as legacy rather than deleted.
What the new diagram shows
CommandManagerpriority queue,ContinuousProfilerSlot,AdhocProfilerSlot) is documented in prose immediately below the diagram and inheartbeat_doc/README_HEARTBEAT.md.webapp/backend(FastAPI) including the new control-plane endpoints (/api/metrics/heartbeat,/api/metrics/profile_request[/bulk],/api/metrics/command_completion,/api/metrics/profiling/host_status),agents-logs-backend,gprofiler_indexer,gprofiler_flamedb_rest.Agent → backend → S3 → SQS → indexer → ClickHouse → flamedb_rest → backend → UI.agent ⇄ backendheartbeat / command, with the UI creating profiling requests through the same backend.Style
The Mermaid theme is tuned for a light-grey canvas with Figma-style pastel cards (per-tier colour: agent = blue, UI = amber, backend = violet, store = pink, AWS = orange) and dashed edges for the control plane. Drop the source into mermaid.live to export PNG / SVG for slides or blog posts.
Why not just regenerate the PNG
Mermaid renders natively on GitHub, lives next to the prose it describes, stays diff-able as the architecture evolves, and avoids drift between code and image-only docs. The legacy PNG remains available for historical reference.
Note
Supersedes the earlier fork-based PR #116, which has been closed.
Test plan
heartbeat_doc/README_HEARTBEAT.md,src/gprofiler/backend/routers/metrics_routes.py,src/gprofiler/frontend/src/components/console/ProfilingStatusPage.jsx,heartbeat_doc/PERFSPECT_DYNAMIC_PROFILING.md).Made with Cursor