簡(jiǎn)介T(mén)racy Profiler 中文用戶手冊(cè)是一份面向C/C等應(yīng)用開(kāi)發(fā)者的跨平臺(tái)性能分析文檔主要覆蓋CPU與GPU實(shí)時(shí)分析、幀分析、采樣分析、遠(yuǎn)程或嵌入式遙測(cè)等場(chǎng)景并突出對(duì)目標(biāo)程序性能影響最小化的設(shè)計(jì)目標(biāo)。資源共1個(gè)docx文件壓縮包約1.26MB內(nèi)容按章節(jié)組織手冊(cè)共八章、結(jié)構(gòu)完整涵蓋Tracy快速概覽、客戶端初始設(shè)置、代碼插樁、數(shù)據(jù)捕獲與存儲(chǔ)、圖形界面分析、區(qū)域統(tǒng)計(jì)導(dǎo)出為CSV、導(dǎo)入外部性能分析數(shù)據(jù)以及配置文件說(shuō)明并涉及Visual Studio、Linux、Android、Docker等平臺(tái)注意事項(xiàng)與故障排除。同時(shí)對(duì)FrameMark、ZoneScoped等關(guān)鍵標(biāo)記用法以及GPU分析Vulkan、D3D、Metal、CUDA、OpenCL等、內(nèi)存分析、鎖、纖程、調(diào)用棧和C API/Python API等高級(jí)特性均有較全面完整的中文說(shuō)明。已有229人瀏覽學(xué)習(xí)適合希望系統(tǒng)掌握Tracy集成方法、快速定位性能瓶頸并優(yōu)化程序表現(xiàn)的開(kāi)發(fā)者閱讀。1. 用 Tracy 做 PHP 性能分析為什么調(diào)試欄里的數(shù)據(jù)比你自己埋點(diǎn)靠譜排查一個(gè)慢接口最常見(jiàn)的方法是進(jìn)入口文件加幾行 microtime打印完再刪掉如果埋點(diǎn)位置不對(duì)整個(gè)流程得重來(lái)一遍。Tracy 性能分析要解決的就是這件事在幾乎不改業(yè)務(wù)代碼的前提下讓頁(yè)面自帶一份包含耗時(shí)、峰值內(nèi)存、加載文件數(shù)的運(yùn)行報(bào)告順帶把異常和日志也接管過(guò)去。網(wǎng)上關(guān)于 Tracy 性能分析的中文資料一直比較零散大多停在安裝步驟這篇直接把落地路徑講透——從 Composer 裝完怎么啟用到用 timer() 做分段埋點(diǎn)、調(diào)哪些參數(shù)再到幾個(gè)真實(shí)踩過(guò)的坑。維護(hù) PHP 服務(wù)、排查慢查詢和內(nèi)存尖峰的人照著做基本能省半天時(shí)間。2. 集成與啟用Tracy 性能分析的最小配置與兩種運(yùn)行模式Tracy 是 PHP 生態(tài)里一個(gè)獨(dú)立的調(diào)試與性能分析組件不依賴特定框架Composer 項(xiàng)目可以直接引入。它不像 Xdebug 那樣需要改 php.ini 或者專門(mén)跑一輪 profiling而是常駐在入口文件里每請(qǐng)求結(jié)束后收集數(shù)據(jù)并在瀏覽器底部渲染一個(gè)診斷欄。理解它的工作原理后面排查問(wèn)題會(huì)順暢很多。2.1 定位一個(gè)掛在入口文件里的性能與錯(cuò)誤診斷面板Tracy 的工作方式可以拆成兩個(gè)鉤子。第一個(gè)是錯(cuò)誤處理器攔截未捕獲的異常和 PHP Notice/Warning按配置決定是渲染藍(lán)屏頁(yè)還是寫(xiě)日志第二個(gè)是 shutdown 回調(diào)在腳本執(zhí)行結(jié)束時(shí)統(tǒng)一收集執(zhí)行時(shí)間、峰值內(nèi)存、加載文件數(shù)并把調(diào)試欄拼到 HTML 尾部。這兩個(gè)鉤子都由Tracy\Debugger::enable()一次性完成注冊(cè)。選型上它和另外兩條常見(jiàn)路線有明顯差異。Xdebug 適合做周期性的深度剖析能輸出 cachegrind 文件給 GUI 工具看但開(kāi)銷大、需要裝擴(kuò)展不適合常開(kāi)。自己寫(xiě) microtime 埋點(diǎn)的問(wèn)題在于埋點(diǎn)代碼會(huì)污染業(yè)務(wù)邏輯測(cè)完還得清一遍而且容易漏掉異常路徑。Tracy 把測(cè)量邏輯放在業(yè)務(wù)代碼外面錯(cuò)誤處理和性能數(shù)據(jù)共用一套載體這是它作為常駐診斷工具的核心優(yōu)勢(shì)。對(duì)于性能分析這個(gè)目標(biāo)你可以把它理解成Tracy 給每個(gè)請(qǐng)求都做了一次輕量級(jí)的 profiling結(jié)果直接泡在頁(yè)面右下角不需要單獨(dú)跑工具。開(kāi)發(fā)者模式開(kāi)了之后連數(shù)據(jù)庫(kù)連接數(shù)、Session 內(nèi)容都在同一塊面板里排查慢接口時(shí)信息是聚攏的不用在 IDE、日志、瀏覽器工具之間來(lái)回切。2.2 Composer 安裝后的最小啟用代碼先裝依賴再在入口文件頂部啟用composer require tracy/tracy?php // public/index.php 的最頂部業(yè)務(wù)代碼之前 require __DIR__ . /../vendor/autoload.php; use Tracy\Debugger; // 第一個(gè)參數(shù)運(yùn)行模式第二個(gè)參數(shù)日志目錄目錄必須存在且可寫(xiě) Debugger::enable(Debugger::Development, __DIR__ . /../log);這段代碼有兩個(gè)關(guān)鍵點(diǎn)。enable()的第一個(gè)參數(shù)是運(yùn)行模式Debugger::Development會(huì)打開(kāi)調(diào)試欄和藍(lán)屏錯(cuò)誤頁(yè)適合本地開(kāi)發(fā)線上環(huán)境應(yīng)該換成Debugger::Production那個(gè)模式下調(diào)試欄不渲染錯(cuò)誤只寫(xiě)日志。第二個(gè)參數(shù)是日志目錄Tracy 捕獲的異常、調(diào)用的Debugger::log()內(nèi)容都會(huì)落到這里目錄不存在或不可寫(xiě)會(huì)導(dǎo)致整個(gè)診斷鏈路靜默失效。我一般會(huì)在require vendor/autoload.php之后立刻調(diào)enable()再加載業(yè)務(wù)配置。原因很簡(jiǎn)單enable()要注冊(cè)錯(cuò)誤處理器放得越早Framework 初始化階段產(chǎn)生的警告才能被它接住。放太晚的話前期錯(cuò)誤已經(jīng)直接打到頁(yè)面上了調(diào)試欄也不會(huì)顯示完整信息。2.3 生產(chǎn)環(huán)境只落日志不彈面板白名單與模式切換生產(chǎn)環(huán)境直接開(kāi) Development 模式是新手最容易犯的錯(cuò)誤——調(diào)試欄會(huì)暴露請(qǐng)求參數(shù)、Session 內(nèi)容而且頁(yè)面底部多一塊渲染邏輯接口耗時(shí)也會(huì)被抬高。正確的做法是用環(huán)境變量加可信 IP 雙重判斷?php require __DIR__ . /../vendor/autoload.php; use Tracy\Debugger; $env getenv(APP_ENV) ?: production; $trustedIps [127.0.0.1, ::1, 10.0.0.%]; $remote $_SERVER[REMOTE_ADDR] ?? ; $isTrusted $trustedIps [] || in_array($remote, $trustedIps, true); $mode ($env dev $isTrusted) ? Debugger::Development : Debugger::Production; Debugger::enable($mode, __DIR__ . /../log); Debugger::$email opsexample.com; // 生產(chǎn)模式下的異常通知地址按需配置這里核心邏輯是只有開(kāi)發(fā)環(huán)境且來(lái)自可信 IP 的請(qǐng)求才展示調(diào)試欄其余場(chǎng)景一律按 Production 模式跑。Debugger::$email是可選配置Production 模式下發(fā)生嚴(yán)重錯(cuò)誤時(shí) Tracy 會(huì)往這個(gè)地址發(fā)郵件摘要適合沒(méi)有獨(dú)立監(jiān)控系統(tǒng)的團(tuán)隊(duì)先頂著用。注意10.0.0.%這類通配是 Tracy 內(nèi)部支持的前綴匹配如果你不想依賴這套規(guī)則完全可以在$trustedIps數(shù)組里只寫(xiě)完整 IP再對(duì)REMOTE_ADDR做前綴判斷邏輯更直觀。3. 讀取與埋點(diǎn)用調(diào)試欄和 timer() 抓頁(yè)面耗時(shí)、內(nèi)存配置啟用后頁(yè)面右下角會(huì)出現(xiàn)調(diào)試欄。對(duì)于性能分析來(lái)說(shuō)調(diào)試欄只是入口真正精確到業(yè)務(wù)環(huán)節(jié)的數(shù)據(jù)要靠手動(dòng)埋點(diǎn)。這一章先說(shuō)怎么看默認(rèn)數(shù)據(jù)再講怎么用 timer 做分段計(jì)時(shí)。3.1 調(diào)試欄怎么讀耗時(shí)、峰值內(nèi)存、加載文件數(shù)調(diào)試欄默認(rèn)展示一組關(guān)鍵指標(biāo)當(dāng)前請(qǐng)求的執(zhí)行時(shí)間、峰值內(nèi)存、加載文件數(shù)、PHP 版本以及一個(gè)可以展開(kāi)的 profile 信息區(qū)。執(zhí)行時(shí)間和峰值內(nèi)存是判斷接口健康度的第一手?jǐn)?shù)據(jù)加載文件數(shù)則能反映 autoload 是否把無(wú)關(guān)類也拉進(jìn)來(lái)了。讀取的時(shí)候要區(qū)分場(chǎng)景。開(kāi)發(fā)模式下調(diào)試欄顯示的耗時(shí)包含 Tracy 自身收集和渲染面板的損耗所以它更適合看相對(duì)變化改了一段查詢后耗時(shí)從 120ms 降到 80ms這個(gè)趨勢(shì)可信但如果你想報(bào)一個(gè)絕對(duì)性能指標(biāo)給上級(jí)應(yīng)該用 Production 模式加日志來(lái)測(cè)。另一個(gè)容易忽略的點(diǎn)是調(diào)試欄的耗時(shí)是整個(gè)請(qǐng)求的端到端數(shù)據(jù)它不會(huì)告訴你慢在哪這時(shí)就需要手動(dòng)埋點(diǎn)把耗時(shí)拆開(kāi)。3.2 用 Tracy\Debugger::timer() 做分段計(jì)時(shí)Debugger::timer()是 Tracy 提供的分段計(jì)時(shí) API。同名計(jì)時(shí)器第一次調(diào)用時(shí)啟動(dòng)第二次調(diào)用時(shí)返回經(jīng)過(guò)的秒數(shù)并自動(dòng)復(fù)位第三次調(diào)用又開(kāi)始新一輪計(jì)時(shí)。用這個(gè)名字配對(duì)機(jī)制可以把一段請(qǐng)求拆成多個(gè)互不干擾的環(huán)節(jié)?php use Tracy\Debugger; Debugger::enable(Debugger::Development, __DIR__ . /log); // 第一次調(diào)用啟動(dòng)名為 sql 的計(jì)時(shí)器 Debugger::timer(sql); $rows fetchUsersFromDb(); // 第二次調(diào)用返回耗時(shí)單位秒這里轉(zhuǎn)成毫秒 $sqlMs Debugger::timer(sql); Debugger::timer(render); renderTemplate($rows); $renderMs Debugger::timer(render); // 第三個(gè)參數(shù)是日志優(yōu)先級(jí)這里用 perf 方便跟業(yè)務(wù)日志區(qū)分 Debugger::log(sprintf(sql %.2f ms, render %.2f ms, $sqlMs * 1000, $renderMs * 1000), perf);參數(shù)上要注意兩點(diǎn)。第一timer()的返回值是秒浮點(diǎn)數(shù)默認(rèn)會(huì)有很多位小數(shù)寫(xiě)日志時(shí)用sprintf控制格式否則日志文件會(huì)很難看。第二日志優(yōu)先級(jí)perf不是固定關(guān)鍵字Tracy 會(huì)按優(yōu)先級(jí)生成對(duì)應(yīng)前綴的日志文件比如你寫(xiě)成perf日志會(huì)落到類似log/perf-2025-xx.log的文件里這樣性能日志和異常日志天然分開(kāi)后處理時(shí) grep 一個(gè)目錄就行。我一般會(huì)用業(yè)務(wù)動(dòng)作名作為timer()的 name比如order.create、export.csv而不是用db、render這種寬泛詞。原因是排查線上慢任務(wù)時(shí)日志里一眼就能看出是哪個(gè)業(yè)務(wù)環(huán)節(jié)慢配合 URI 字段就能定位到具體接口不用再猜。3.3 把耗時(shí)寫(xiě)進(jìn)日志CLI 與異步任務(wù)里的性能記錄調(diào)試欄依賴瀏覽器渲染CLI 腳本、隊(duì)列進(jìn)程、定時(shí)任務(wù)里它完全派不上用場(chǎng)。這些場(chǎng)景的常見(jiàn)做法是后端直接啟用 Production 模式用Debugger::log()把性能數(shù)據(jù)落盤(pán)?php // bin/worker.php 隊(duì)列消費(fèi)腳本 require __DIR__ . /../vendor/autoload.php; use Tracy\Debugger; // CLI 環(huán)境不需要渲染調(diào)試欄直接用 Production 模式日志照常工作 Debugger::enable(Debugger::Production, __DIR__ . /../log); Debugger::timer(batch); processQueueBatch(); $elapsed Debugger::timer(batch); Debugger::log(sprintf( batch done in %.2f s, peak mem %.1f MB, items %d, $elapsed, memory_get_peak_usage(true) / 1048576, $processedCount ), perf);這段代碼把核心性能指標(biāo)拼成一行寫(xiě)入 perf 日志任務(wù)總耗時(shí)、峰值內(nèi)存、處理?xiàng)l數(shù)。memory_get_peak_usage(true)拿到的是系統(tǒng)分配給 PHP 的真實(shí)峰值內(nèi)存比memory_get_usage()更接近 OOM 風(fēng)險(xiǎn)線。日志級(jí)別用perf方便后續(xù)統(tǒng)一收集和分析。我自己的習(xí)慣是在隊(duì)列框架的基類里做一次這樣的埋點(diǎn)而不是在每個(gè)任務(wù)里重復(fù)寫(xiě)。因?yàn)槿蝿?wù)跑完以后你真正關(guān)心的是有沒(méi)有某個(gè)隊(duì)列積壓、某個(gè)處理函數(shù)內(nèi)存泄漏統(tǒng)一埋點(diǎn)能直接產(chǎn)出一份持續(xù)積累的性能數(shù)據(jù)而不是臨時(shí)打幾條日志。4. 必調(diào)參數(shù)maxDepth、maxLength 和 dump 的取舍Tracy 的 dump 功能非常方便但默認(rèn)參數(shù)在真實(shí)業(yè)務(wù)數(shù)據(jù)面前往往不夠用。要么 dump 出來(lái)一大片全是省略號(hào)要么調(diào)大參數(shù)后頁(yè)面直接卡死。這一章把控制轉(zhuǎn)儲(chǔ)深度的參數(shù)講清楚。4.1 三個(gè)控制轉(zhuǎn)儲(chǔ)行為的參數(shù)參數(shù)作用常見(jiàn)開(kāi)發(fā)值說(shuō)明Debugger::$maxDepthdump 數(shù)組/對(duì)象時(shí)展開(kāi)的最大層級(jí)35值太大會(huì)把整個(gè)對(duì)象圖遍歷一遍注意循環(huán)引用Debugger::$maxLength單個(gè)字符串最多顯示多少字符3001500超出部分會(huì)被截?cái)嗖?biāo)記不影響真實(shí)數(shù)據(jù)Debugger::$maxAttachedLength內(nèi)聯(lián)附件圖片等讀取的最大字節(jié)數(shù)約 50000以你安裝版本為準(zhǔn)一般不用改涉及附件調(diào)試時(shí)才需要?jiǎng)舆@三個(gè)參數(shù)只影響 dump 的顯示和轉(zhuǎn)儲(chǔ)過(guò)程不會(huì)改業(yè)務(wù)數(shù)據(jù)本身。maxDepth是性能敏感度最高的一個(gè)Tracy 要把數(shù)組和對(duì)象遞歸遍歷并生成可折疊的 HTML深度每加一層工作量可能翻倍。一個(gè)上百層的嵌套結(jié)構(gòu)開(kāi)滿深度去 dump頁(yè)面卡住幾秒鐘很常見(jiàn)。maxLength控制長(zhǎng)字符串的截?cái)唷＞€上接口返回的 JSON 動(dòng)輒幾千字符默認(rèn)值可能只夠看到開(kāi)頭排查響應(yīng)體問(wèn)題時(shí)需要把它調(diào)大但別一次拉滿。我一般先看截?cái)嚅_(kāi)頭能不能定位問(wèn)題不夠再加省得日志刷屏。4.2 dump 大型數(shù)據(jù)時(shí)的內(nèi)存陷阱與參數(shù)設(shè)置排查內(nèi)存泄漏時(shí)很多人喜歡 dump 一個(gè)復(fù)雜對(duì)象圖看引用關(guān)系結(jié)果內(nèi)存沒(méi)查出來(lái)頁(yè)面先 OOM 了。合理做法是先限制轉(zhuǎn)儲(chǔ)范圍再觀察結(jié)構(gòu)?php use Tracy\Debugger; // 全局限制轉(zhuǎn)儲(chǔ)兩層就停字符串只顯示開(kāi)頭 300 字符 Debugger::$maxDepth 2; Debugger::$maxLength 300; $payload $someService-fetchLargeResponse(); // 可能是一個(gè)很大的嵌套數(shù)組/對(duì)象 // 先看結(jié)構(gòu)和字段名而不是看全量?jī)?nèi)容 dump($payload);注釋里已經(jīng)說(shuō)明了邏輯dump()是 Tracy 提供的全局函數(shù)效果和Tracy\Debugger::dump()相同輸出可折疊的 HTML點(diǎn)擊展開(kāi)子節(jié)點(diǎn)。限制maxDepth 2后你看到的是數(shù)組第一層字段和每個(gè)子項(xiàng)的類型摘要已經(jīng)足夠定位“哪個(gè)字段帶著巨大的數(shù)據(jù)”這類問(wèn)題而不會(huì)把整個(gè)結(jié)構(gòu)全量渲染。如果確實(shí)需要深入看某個(gè)節(jié)點(diǎn)的完整內(nèi)容不要在全局把maxDepth調(diào)到很大而是在轉(zhuǎn)儲(chǔ)前臨時(shí)局部設(shè)置看完立刻改回?php Debugger::$maxDepth 1; dump($payload[items][0]); // 只展開(kāi)這一層的內(nèi)部 Debugger::$maxDepth 2; // 改回常用值參數(shù)位置放在enable()之后、dump()之前即可Tracy 沒(méi)有專門(mén)的配置階段運(yùn)行時(shí)改屬性立刻生效這既是優(yōu)點(diǎn)也是坑——埋點(diǎn)代碼記得刪不然別人改代碼時(shí)行為會(huì)很詭異。4.3 線上禁用 d()為什么調(diào)試欄拖慢接口d()是dump() die()的組合函數(shù)適合臨時(shí)打斷執(zhí)行流看中間結(jié)果但線上絕不能留。d($x)執(zhí)行到這一行就直接終止請(qǐng)求后面所有邏輯都不跑而且響應(yīng)內(nèi)容也會(huì)因?yàn)樘崆爸袛喽兊貌豢捎们岸四玫降目赡苁前雮€(gè) HTML 加一段調(diào)試數(shù)據(jù)。更隱蔽的問(wèn)題出現(xiàn)在調(diào)試欄本身。即使你只在開(kāi)發(fā)環(huán)境開(kāi)了調(diào)試欄它也會(huì)在每次請(qǐng)求時(shí)收集 Session、請(qǐng)求參數(shù)、加載文件列表并在頁(yè)面底部注入調(diào)試欄的 HTML 和 JS。對(duì)生產(chǎn)環(huán)境的壓測(cè)來(lái)說(shuō)這個(gè)開(kāi)銷會(huì)直接影響 QPS 數(shù)字所以性能測(cè)試環(huán)境我強(qiáng)烈建議用 Production 模式只留日志不要開(kāi)調(diào)試欄。一個(gè)相對(duì)安全的調(diào)試開(kāi)關(guān)是用環(huán)境變量包一層?php // 只有顯式設(shè)置了 DEBUG_DUMP 才允許 d() 生效 if (!empty($_ENV[DEBUG_DUMP])) { d($payload); }這樣即使代碼不小心發(fā)布上線沒(méi)有環(huán)境變量也不會(huì)觸發(fā)die()算是一道保險(xiǎn)。團(tuán)隊(duì)里如果有新人習(xí)慣用d()調(diào)試這個(gè)習(xí)慣值得推廣開(kāi)。5. 落地排查性能分析中的 5 個(gè)典型坑這一章的每條坑都是實(shí)際接入 Tracy 服務(wù)時(shí)踩過(guò)的按「現(xiàn)象 → 原因 → 解決」寫(xiě)方便直接對(duì)照。5.1 現(xiàn)象一開(kāi)了調(diào)試欄接口耗時(shí)翻倍開(kāi)發(fā)環(huán)境某個(gè)接口原本 80ms啟用調(diào)試欄后變成 160ms。壓測(cè)時(shí)更明顯開(kāi)與不開(kāi)差了將近兩成。原因在于調(diào)試欄要做數(shù)據(jù)采集和渲染收集 Session、請(qǐng)求參數(shù)、加載文件列表還要在頁(yè)面底部注入一段 HTML 和 JS這一步發(fā)生在請(qǐng)求的完全結(jié)束前占的是真實(shí)響應(yīng)時(shí)間。測(cè)量工具改變被測(cè)系統(tǒng)這是預(yù)期內(nèi)的物理?yè)p耗不代表 Tracy 有嚴(yán)重 bug。解決時(shí)先想清楚數(shù)據(jù)用途看趨勢(shì)、優(yōu)化邏輯就用開(kāi)發(fā)模式出報(bào)告、壓測(cè)必須切到 Production 模式靠日志測(cè)。另外把maxDepth、maxLength調(diào)到夠用即可越小的轉(zhuǎn)儲(chǔ)范圍意味著越少的額外開(kāi)銷。5.2 現(xiàn)象二CLI 腳本里看不到任何性能數(shù)據(jù)在 cron 腳本里enable(Debugger::Development)后頁(yè)面完全沒(méi)有調(diào)試欄輸出腳本本身也沒(méi)報(bào)錯(cuò)以為 Tracy 集成失敗了。原因不難理解調(diào)試欄的渲染依賴瀏覽器請(qǐng)求的 HTML 輸出CLI 進(jìn)程沒(méi)有這個(gè)概念enable()即便成功注冊(cè)了錯(cuò)誤處理器也沒(méi)地方渲染調(diào)試欄。解決方法是 CLI 任務(wù)統(tǒng)一用日志載體。我在隊(duì)列消費(fèi)腳本里只保留Debugger::enable(Debugger::Production, $logDir)然后對(duì)核心環(huán)節(jié)調(diào)Debugger::timer()配合Debugger::log()日志文件就是可視化數(shù)據(jù)源。后續(xù)要分析時(shí)寫(xiě)幾行腳本把 perf 日志聚合一下比任何面板都好用。5.3 現(xiàn)象三藍(lán)屏頁(yè)白屏日志目錄沒(méi)權(quán)限配置好 Tracy 后打開(kāi)一個(gè)錯(cuò)誤頁(yè)面沒(méi)有出現(xiàn)藍(lán)屏錯(cuò)誤頁(yè)而是白屏log 目錄也空。原因通常是日志目錄不存在或 php-fpm 運(yùn)行用戶沒(méi)有寫(xiě)權(quán)限。Tracy 在無(wú)法寫(xiě)日志時(shí)會(huì)放棄渲染錯(cuò)誤頁(yè)避免把異常信息二次暴露所以表現(xiàn)成白屏而不是報(bào)錯(cuò)。解決分兩步先確認(rèn)目錄存在且可寫(xiě)再在enable()前做一次檢查避免靜默失敗。一個(gè)簡(jiǎn)單的前置檢查?php $logDir __DIR__ . /../log; if (!is_dir($logDir) !mkdir($logDir, 0775, true)) { fwrite(STDERR, log directory is not writable: $logDir\n); exit(1); } Debugger::enable(Debugger::Development, $logDir);注意 php-fpm 進(jìn)程和命令行用戶經(jīng)常不是同一個(gè)本地 CLI 能寫(xiě)不代表 web 用戶能寫(xiě)部署后最好手動(dòng)訪問(wèn)一次錯(cuò)誤頁(yè)面驗(yàn)證。5.4 現(xiàn)象四dump 大數(shù)組內(nèi)存暴增甚至 OOM為了看清某個(gè)接口返回的完整結(jié)構(gòu)把maxDepth調(diào)到 10然后dump($payload)頁(yè)面直接卡死或報(bào)內(nèi)存耗盡。原因有兩個(gè)深層遍歷成本隨深度指數(shù)增長(zhǎng)循環(huán)引用會(huì)讓遍歷出現(xiàn)更多重復(fù)路徑。解決方法是前面提到的控制轉(zhuǎn)儲(chǔ)范圍先低深度看結(jié)構(gòu)再局部深入另外如果只是想看某個(gè)字段的完整值直接存日志看原始數(shù)據(jù)比 dump 更省。真的需要 dump 大型結(jié)果集時(shí)先array_map截取一部分字段重建數(shù)組再交給 dump開(kāi)銷會(huì)小很多。5.5 現(xiàn)象五timer() 拿到的耗時(shí)和預(yù)期不符外層計(jì)時(shí)器返回 0ms或者某個(gè)分段耗時(shí)明顯偏小。原因是對(duì)timer()同名配對(duì)機(jī)制理解不透同名計(jì)時(shí)器第二次調(diào)用會(huì)返回耗時(shí)并復(fù)位第三次調(diào)用又是新一輪計(jì)時(shí)如果外層內(nèi)層用了同一個(gè) name內(nèi)層先返回復(fù)位外層拿到的就是從復(fù)位點(diǎn)到外層結(jié)束的一小段等于白測(cè)。解決方法是每個(gè)分段分配唯一 name或者干脆用閉包封裝避免手寫(xiě)配對(duì)的低級(jí)錯(cuò)誤?php function profile_call(string $name, callable $fn): float { Debugger::timer($name); $fn(); return Debugger::timer($name); } $dbMs profile_call(profile.db, fn() queryDb()) * 1000;封裝后的profile_call名字自帶業(yè)務(wù)含義返回值直接就是這段邏輯的耗時(shí)沒(méi)有配對(duì)和復(fù)位的理解成本適合在內(nèi)部工具函數(shù)里統(tǒng)一調(diào)用。6. 進(jìn)階把 Tracy 調(diào)試欄擴(kuò)展成團(tuán)隊(duì)自己的性能基線與慢請(qǐng)求歸檔默認(rèn)調(diào)試欄展示的是總耗時(shí)和總內(nèi)存業(yè)務(wù)上更需要看的往往是數(shù)據(jù)庫(kù)、外部 HTTP、Redis 各自花了多少。Tracy 提供了面板接口可以自定義標(biāo)簽頁(yè)掛到調(diào)試欄上。6.1 自定義 IBarPanel把數(shù)據(jù)庫(kù)耗時(shí)單獨(dú)掛到調(diào)試欄實(shí)現(xiàn)Tracy\IBarPanel接口getTab()顯示在調(diào)試欄上的短標(biāo)題getPanel()返回點(diǎn)擊后展開(kāi)的 HTML 內(nèi)容?php use Tracy\IBarPanel; use Tracy\Debugger; class DbPanel implements IBarPanel { private array $events []; public function add(string $sql, float $seconds): void { $this-events[] [$sql, $seconds]; } public function getTab(): string { $total array_sum(array_column($this-events, 1)); return sprintf(DB %.1f ms, $total * 1000); } public function getPanel(): string { $html table stylefont: 12px/1.5 monospace;border-collapse:collapse; foreach ($this-events as [$sql, $seconds]) { $html . sprintf( trtd stylepadding:2px 8px%.2f ms/tdtd%s/td/tr, $seconds * 1000, htmlspecialchars($sql, ENT_QUOTES) ); } return $html . /table; } } $dbPanel new DbPanel(); // 必須在 enable() 之后注冊(cè) Debugger::getBar()-addPanel($dbPanel); // 業(yè)務(wù)查詢處埋點(diǎn) $t Debugger::timer(sql:user); $pdo-query($query); $dbPanel-add($query, Debugger::timer(sql:user));getTab()里的array_sum(array_column(...))把本次請(qǐng)求所有 SQL 耗時(shí)匯總調(diào)試欄直接顯示總耗面板展開(kāi)則能看到每條 SQL 的獨(dú)立耗時(shí)。注意getPanel()返回的 HTML 里拼接了外部輸入的 SQL 語(yǔ)句必須用htmlspecialchars轉(zhuǎn)義否則 SQL 里帶個(gè)尖括號(hào)就能破壞面板布局這屬于基礎(chǔ)安全習(xí)慣。注冊(cè)面板要在enable()之后調(diào)用容器初始化階段放這就行。6.2 請(qǐng)求結(jié)束自動(dòng)寫(xiě)性能基線 JSONL調(diào)試欄適合開(kāi)發(fā)期點(diǎn)著看真正要發(fā)現(xiàn)“接口從 80ms 漲到 160ms”這種回歸靠的是持續(xù)的性能基線。用register_shutdown_function在每次請(qǐng)求結(jié)束時(shí)把關(guān)鍵指標(biāo)追加到 JSONL 文件?php register_shutdown_function(function (): void { $row [ time date(DATE_ATOM), uri $_SERVER[REQUEST_URI] ?? cli, duration_s Debugger::timer() ?: 0, peak_mb memory_get_peak_usage(true) / 1048576, ]; file_put_contents( __DIR__ . /../log/perf-baseline.jsonl, json_encode($row) . \n, FILE_APPEND | LOCK_EX ); });每次請(qǐng)求一行 JSON累積一段時(shí)間后就能做分位數(shù)統(tǒng)計(jì)找出哪些接口的耗時(shí)在緩慢惡化。Debugger::timer()不傳參數(shù)時(shí)用的是默認(rèn)計(jì)時(shí)器從enable()之后就開(kāi)始計(jì)到請(qǐng)求結(jié)束時(shí)正好是總耗時(shí)。LOCK_EX防止并發(fā)寫(xiě)時(shí)候文件交錯(cuò)。這套思路從 Tracy 的性能分析延展成了團(tuán)隊(duì)自己的性能基線開(kāi)發(fā)期看調(diào)試欄測(cè)試期跑幾輪壓測(cè)看 JSONL上線后配合定時(shí)任務(wù)每天算一次 p95比臨時(shí)抓包定位快得多。我自己早期做性能優(yōu)化時(shí)總習(xí)慣把maxDepth拉到很大去看對(duì)象圖結(jié)果在一次壓測(cè)里調(diào)試欄的采集損耗讓 QPS 掉了接近兩成才真正明白 Tracy 的性能數(shù)據(jù)要區(qū)分“給人看”和“給機(jī)器存”兩條路徑——前者用調(diào)試欄后者用日志。希望這套落地路徑能幫你少走這段彎路直接把 Tracy 的性能分析用起來(lái)。本文還有配套的精品資源點(diǎn)擊獲取