Skip to content

Commit a78590c

Browse files
author
Sunil Thaha
authored
Merge pull request #2305 from vprashar2929/docs-profile
docs: add profiling workflow documentation
2 parents f67206a + 02856c5 commit a78590c

File tree

4 files changed

+164
-5
lines changed

4 files changed

+164
-5
lines changed

‎.github/workflows/profiling.yaml‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,6 @@ jobs:
2828
if: needs.check-changes.outputs.changes == 'true'
2929
runs-on: ubuntu-latest
3030
steps:
31-
- name: Install Graphviz
32-
run: |
33-
sudo apt-get update
34-
sudo apt-get install -y graphviz
35-
3631
- name: Install Docker
3732
shell: bash
3833
run: |

‎docs/developer/assets/profiling.png‎

190 KB
Loading

‎docs/developer/assets/profiling.uml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
@startuml Profiling Report Workflow Sequence
2+
' NOTE: Render using http://sujoyu.github.io/plantuml-previewer or any PlantUML tool
3+
title Profiling Report Workflow
4+
skinparam sequenceMessageAlign center
5+
skinparam responseMessageBelowArrow true
6+
skinparam maxMessageSize 150
7+
skinparam style strictuml
8+
actor "Contributor" as Dev
9+
participant "GitHub Repo" as SR
10+
box "GitHub Actions" #LightBlue
11+
participant "Workflow Runner" as Runner
12+
end box
13+
participant "Artifact Storage" as Artifacts
14+
participant "External Workflow" as ExtWF
15+
note over ExtWF: Separate PR Comment Workflow\n(triggered on workflow_run event)
16+
== Trigger ==
17+
Dev -> SR: Create or update Pull Request
18+
SR -> Runner: Trigger profiling-report workflow\n(on: pull_request)
19+
== Job: check-changes ==
20+
group Change Detection
21+
Runner -> Runner: Checkout source code
22+
Runner -> Runner: Filter paths for changes\n(using dorny/paths-filter)
23+
note right: Outputs 'changes' if relevant files modified
24+
end
25+
== Job: profiling ==
26+
note right of Runner: Needs check-changes;\nRuns if changes == 'true'
27+
group Environment Setup
28+
Runner -> Runner: Install and Verify Docker
29+
Runner -> Runner: Checkout source code
30+
Runner -> Runner: Setup Go environment
31+
Runner -> Runner: Install pprof
32+
end
33+
group Profiling Execution
34+
Runner -> Runner: Enable fake CPU meter in configs
35+
Runner -> Runner: Run Docker Compose services\n(build and start kepler-dev/latest in detach mode)
36+
Runner -> Runner: Run must-gather (always)\n(collect logs, metrics, etc.)
37+
Runner -> Runner: Sleep for 10 seconds
38+
Runner -> Runner: Capture CPU/Memory profiling\n(using hack/reports/profiling.sh capture --duration 60)
39+
Runner -> Runner: Compare profiling results\n(using hack/reports/profiling.sh compare)
40+
end
41+
group Artifact Upload
42+
Runner -> Artifacts: Upload profiling artifacts\n(name: profile-artifacts-${{ github.event.pull_request.number }})
43+
end
44+
== Job: generate-comment-message ==
45+
note right of Runner: Needs profiling;\nRuns if profiling success
46+
group Message Generation
47+
Runner -> Runner: Checkout source code
48+
Runner -> Runner: Setup Go environment
49+
Runner -> Runner: Install pprof
50+
Runner -> Artifacts: Download profiling artifacts
51+
Runner -> Runner: Generate comment messages\n(using hack/reports/profiling.sh output;\nincludes download instructions)
52+
end
53+
group Message Artifact Upload
54+
Runner -> Artifacts: Upload message artifact\n(name: message;\npath: /tmp/message-*.txt)
55+
note right: This upload enables a separate PR Comment workflow\nto download the artifact and post a comment on the PR
56+
Artifacts --> ExtWF: Triggers PR Comment workflow\n(on workflow_run event;\ndownloads message and comments on PR)
57+
end
58+
== Complete ==
59+
Runner --> SR: Workflow complete
60+
@enduml

‎docs/developer/profiling.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# 📊 Profiling Workflow
2+
3+
The Profiling workflow is an automated GitHub Actions workflow that generates and compares performance profiles for Kepler when changes are made to the codebase. This workflow helps developers understand the performance impact of their changes by providing detailed CPU and memory profiling data.
4+
5+
## 🎯 Purpose
6+
7+
The profiling workflow serves several critical purposes:
8+
9+
1. **📉 Performance Regression Detection**: Automatically identifies potential performance degradations introduced by code changes
10+
2. **📈 Resource Usage Analysis**: Provides detailed insights into CPU and memory consumption patterns
11+
3. **⚖️ Comparative Analysis**: Compares performance metrics between the development version and the latest stable version
12+
4. **🔄 Continuous Performance Monitoring**: Ensures performance considerations are part of the development process
13+
14+
## 🔄 Workflow Overview
15+
16+
![Profiling Workflow Overview](assets/profiling.png)
17+
18+
## 🏗️ Workflow Structure
19+
20+
The profiling workflow consists of three main jobs:
21+
22+
### 1. 🔍 Check Changes Job
23+
24+
- **🎯 Purpose**: Determines if profiling should run based on file changes
25+
- **⚡ Trigger**: Runs on every pull request
26+
27+
### 2. 📊 Profiling Job
28+
29+
- **🎯 Purpose**: Executes the actual profiling process
30+
- **⚠️ Conditions**: Only runs if relevant changes are detected
31+
32+
### 3. 💬 Generate Comment Message Job
33+
34+
- **🎯 Purpose**: Creates a formatted comment message with profiling results
35+
- **⚠️ Conditions**: Only runs if profiling job succeeds
36+
- **📦 Output**: Generates artifacts containing:
37+
- Formatted profiling comparison results
38+
- Download instructions for profiling artifacts
39+
- GitHub CLI commands for artifact retrieval
40+
41+
## ✨ Key Features
42+
43+
### 🤖 Automated Environment Setup
44+
45+
The workflow automatically provisions a complete testing environment including:
46+
47+
- 🐳 Docker containerization for isolated testing
48+
- 🔄 Both development and production Kepler versions
49+
50+
### 🔬 Comprehensive Profiling
51+
52+
- **⏱️ Duration**: 60-second profiling sessions for statistically significant data
53+
- **📊 Metrics**: CPU and memory usage patterns
54+
- **🔀 Comparison**: Side-by-side analysis of different versions
55+
56+
### 📦 Artifact Management
57+
58+
- **🗓️ Retention**: Profiling artifacts retained for 5 days
59+
- **🏷️ Naming**: Artifacts named with PR numbers for easy identification
60+
- **📥 Access**: Multiple download methods provided (web interface, GitHub CLI)
61+
62+
## 🔐 Security Considerations
63+
64+
### 🤔 Why Separate Comment Message Generation?
65+
66+
The workflow uploads comment messages as artifacts rather than directly posting comments to pull requests. This approach addresses critical security concerns outlined in [issue #2287](https://github.com/sustainable-computing-io/kepler/issues/2287).
67+
68+
### ⚠️ Security Challenge
69+
70+
Using the `pull_request_target` event for PR comments creates security risks because:
71+
72+
- ⚡ The workflow runs in the context of the target branch with full repository permissions
73+
- 🛡️ Malicious code in PR branches could potentially access sensitive information
74+
- 🔓 Direct comment posting from PR contexts poses privilege escalation risks
75+
76+
### ✅ Secure Solution
77+
78+
The current approach implements a two-stage security model:
79+
80+
1. **🔄 Source Workflow** (this profiling workflow):
81+
- 🔒 Runs in the limited context of the PR branch
82+
- 🛡️ Generates comment content safely
83+
- 📤 Uploads message as an artifact (no direct repository access)
84+
85+
2. **💬 Dedicated PR Comment Workflow**:
86+
- 🔐 Runs separately using the safer `workflow_run` event trigger
87+
- 📥 Downloads the pre-generated comment artifact
88+
- 📝 Posts comments with proper base branch context
89+
- 🛡️ Maintains security isolation
90+
91+
### 🎯 Benefits of This Approach
92+
93+
- **🔐 Security Isolation**: PR comment workflows run in base branch context, not PR context
94+
- **🛡️ Reduced Attack Surface**: Limited permissions for content generation workflows
95+
- **📋 Audit Trail**: Clear separation of content generation and posting actions
96+
- **♻️ Reusability**: Comment generation pattern can be reused across multiple workflows
97+
98+
## 🚀 Usage
99+
100+
The profiling workflow automatically triggers on pull requests that modify relevant files. No manual intervention is required. Results are available through:
101+
102+
1. **📊 GitHub Actions Summary**: View workflow execution details and download artifacts
103+
2. **💬 PR Comments**: Automated comments with profiling summaries (posted by separate workflow)
104+
3. **📦 Artifacts**: Detailed profiling data available for download and local analysis

0 commit comments

Comments
 (0)