From 1b98ebd10a2807ea69fd46d96ab8b9c606aab134 Mon Sep 17 00:00:00 2001
From: Fabien O'Carroll <fabien@allou.is>
Date: Thu, 25 Sep 2025 14:40:24 +0100
Subject: [PATCH] [WIP] Basic profiling

---
 PROFILING.md       | 31 +++++++++++++++++++++++++++++++
 docker-compose.yml |  2 ++
 package.json       |  4 +++-
 3 files changed, 36 insertions(+), 1 deletion(-)
 create mode 100644 PROFILING.md

diff --git a/PROFILING.md b/PROFILING.md
new file mode 100644
index 000000000..e137e0cb0
--- /dev/null
+++ b/PROFILING.md
@@ -0,0 +1,31 @@
+# CPU Profiling Guide
+
+This guide explains how to profile the ActivityPub server to diagnose CPU spikes and performance issues.
+
+## Quick Start
+
+**Start profiling mode:**
+```bash
+yarn dev:profile
+```
+
+## Profile Files Location
+
+CPU profiles are saved to the `./profiles/` directory with timestamps:
+```
+profiles/
+├── CPU.20240123.142547.001.0.001.cpuprofile
+├── CPU.20240123.142612.002.0.001.cpuprofile
+└── ...
+```
+
+## Analyzing Profiles
+
+### Chrome DevTools
+
+1. Open Chrome and go to `chrome://inspect`
+2. Click "Open dedicated DevTools for Node"
+3. Go to the **"Performance"** tab (not Profiler tab)
+4. Click the "Load profile" button (folder icon)
+5. Select your `.cpuprofile` file
+6. Analyze the flame graph and call tree
diff --git a/docker-compose.yml b/docker-compose.yml
index f9294475a..33beb0f48 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -7,6 +7,7 @@ services:
       - ./src:/opt/activitypub/src
       - ./dist:/opt/activitypub/dist
       - dev-content:/opt/activitypub/content
+      - ./profiles:/opt/activitypub/profiles
     environment:
       - PORT=8080
       - MYSQL_USER=ghost
@@ -34,6 +35,7 @@ services:
       - REDIS_HOST=redis
       - REDIS_PORT=6379
       - FEDIFY_KV_STORE_TYPE=redis
+      - ENABLE_PROFILING=${ENABLE_PROFILING:-false}
     command: yarn build:watch
     depends_on:
       migrate:
diff --git a/package.json b/package.json
index a89bbb377..20133a1bd 100644
--- a/package.json
+++ b/package.json
@@ -8,9 +8,11 @@
   "type": "module",
   "scripts": {
     "build": "esbuild src/app.ts --sourcemap --platform=neutral --bundle --packages=external --outfile=dist/app.js",
-    "build:watch": "concurrently \"yarn build --watch\" \"node --inspect=0.0.0.0:9229 --watch dist/app.js\"",
+    "build:watch": "concurrently \"yarn build --watch\" \"yarn _start:dev\"",
+    "_start:dev": "node --inspect=0.0.0.0:9229 ${ENABLE_PROFILING:+--cpu-prof --cpu-prof-dir=/opt/activitypub/profiles} --watch dist/app.js",
     "predev": "docker compose build migrate fake-gcs",
     "dev": "docker compose up activitypub nginx -d --build",
+    "dev:profile": "ENABLE_PROFILING=true docker compose up activitypub nginx -d --build",
     "stop": "docker compose stop",
     "db": "docker compose exec mysql mysql -uroot -proot activitypub",
     "fix": "docker compose down --rmi all activitypub activitypub-testing cucumber-tests nginx",