指南：Apify Actor 日志系統(tǒng)深度解析（apify/log 與 Actor.log 全級別使用規(guī)范）)
Agentic Awesome Skills 實戰(zhàn)指南Apify Actor 日志系統(tǒng)深度解析apify/log 與 Actor.log 全級別使用規(guī)范【免費下載鏈接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.項目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills導(dǎo)讀本文以 agentic-awesome-skills 倉庫內(nèi)apify-actor-development技能的官方日志參考文檔為主體系統(tǒng)講解 Apify Actor 在 JavaScript/TypeScript 與 Python 兩大技術(shù)棧下的日志規(guī)范為什么必須使用apify/log包與Actor.log日志器它們提供的全部日志級別各自適用于什么場景以及如何通過正確的日志實踐避免憑據(jù)泄露、提升可觀測性。讀完本文你將掌握一套可直接應(yīng)用于 Actor 開發(fā)全流程本地調(diào)試、平臺運行、排障定位的安全日志方案并能對照倉庫源碼級參考文檔快速檢索細節(jié)。為什么 Actor 日志必須走專用日志器安全是第一優(yōu)先級在 Apify Actor 開發(fā)中日志絕不只是把信息打印出來。apify-actor-development技能的日志參考文檔 references/logging.md 在開篇就以加粗形式給出了一條硬性規(guī)定JavaScript / TypeScript必須使用apify/log包Python必須使用Actor.log日志器。其核心原因在于這兩個日志器內(nèi)置了關(guān)鍵的安全脫敏邏輯critical security logic能夠自動審查并隱藏日志中的敏感數(shù)據(jù)——包括 Apify Token、API Key、憑據(jù)等從而防止它們在運行日志中被意外暴露。對應(yīng)的技能主文檔 SKILL.md 從正反兩面強化了這一要求最佳實踐清單Do中明確Always useapify/logpackage— censors sensitive data (API keys, tokens, credentials)禁止清單Dont中明確不要用console.log()或print()代替 Apify 日志器——它們會繞過憑據(jù)脫敏機制。這意味著如果 Actor 代碼里殘留了console.log()/print()一旦日志中包含 Token 或憑據(jù)就會以明文形式進入日志流可能在 Apify Console、第三方日志采集系統(tǒng)中被留存和擴散。因此使用專用日志器在 Apify 生態(tài)中首先是安全實踐其次才是可觀測性實踐。JavaScript / TypeScriptapify/log的十個日志級別在 JS/TS 技術(shù)棧中apify/log包提供了 10 個日志方法覆蓋從最詳細的調(diào)試信息到系統(tǒng)內(nèi)部消息的完整梯度。下表完整繼承自參考文檔日志方法級別定位適用場景l(fā)og.debug()調(diào)試級詳細的診斷信息用于函數(shù)內(nèi)部的細粒度追蹤log.info()信息級一般性提示消息如 API 請求、成功操作log.warning()警告級潛在問題場景如校驗失敗、意外狀態(tài)log.warningOnce()去重警告相同警告消息只記錄一次防止日志刷屏log.error()錯誤級實際發(fā)生的錯誤與失敗log.exception()異常級捕獲到的帶堆棧信息的異常log.perf()性能級性能指標與耗時信息log.deprecated()棄用級關(guān)于已棄用代碼的警告log.softFail()軟失敗級不中斷執(zhí)行的非致命失敗如輸入校驗失敗、跳過的條目log.internal()內(nèi)部級系統(tǒng)/內(nèi)部消息JS/TS 典型用法示例基于上述級別定義一個規(guī)范的 Actor 日志調(diào)用大致如下import { log } from apify/log; // 函數(shù)內(nèi)部的細粒度診斷 log.debug(Processing item, { itemId, attempt }); // 一般性信息API 請求、成功操作 log.info(Requesting page, { url }); log.info(Successfully pushed items, { count }); // 潛在問題校驗失敗、意外狀態(tài) log.warning(Unexpected input format, using defaults); log.warningOnce(Rate limit approaching); // 同類警告只出現(xiàn)一次 // 實際錯誤 log.error(Failed to fetch page, { url, statusCode }); // 捕獲到的異常帶堆棧 try { // ... } catch (err) { log.exception(err, Unexpected error in handler); } // 性能計時 log.perf(Crawl duration, { seconds: elapsed }); // 棄用提示 log.deprecated(Option X is deprecated, use Y instead); // 非致命失敗輸入校驗失敗、跳過條目 log.softFail(Skipping item due to missing field, { itemId }); // 系統(tǒng)內(nèi)部消息 log.internal(Initializing actor runtime);級別選擇的最佳實踐JS/TS參考文檔給出了清晰的分級使用準則log.debug()用于函數(shù)內(nèi)部的詳細操作級診斷適合埋點在循環(huán)、數(shù)據(jù)處理等高頻路徑中僅在需要排障時可調(diào)高日志級別查看log.info()用于一般性信息如 API 請求發(fā)出、操作成功完成log.warning()用于可能出問題的情況如校驗失敗、出現(xiàn)非預(yù)期狀態(tài)程序仍能繼續(xù)運行l(wèi)og.error()用于真正發(fā)生的錯誤與失敗log.exception()用于被try/catch捕獲、需要保留堆棧信息的異常。合理運用這套分級可以讓日志在信息充分與信噪比可控之間取得平衡常態(tài)下以info為基線排障時通過debug獲取細節(jié)warning/error則在 Console 中形成清晰的告警信號。PythonActor.log的日志級別在 Python 技術(shù)棧中Apify Actor 日志器Actor.log同樣內(nèi)置憑據(jù)脫敏邏輯且必須使用Actor.log而非 Python 內(nèi)置的print()。參考文檔列出 5 個日志方法日志方法級別定位適用場景Actor.log.debug()調(diào)試級詳細診斷信息用于函數(shù)內(nèi)部Actor.log.info()信息級一般性提示消息如 API 請求、成功操作Actor.log.warning()警告級潛在問題如校驗失敗、意外狀態(tài)Actor.log.error()錯誤級實際錯誤與失敗Actor.log.exception()異常級帶堆棧信息的異常Python 典型用法示例from apify import Actor async def main(): await Actor.init() # 函數(shù)內(nèi)部診斷 Actor.log.debug(Processing item, extra{item_id: item_id}) # 一般性信息 Actor.log.info(Fetching page, extra{url: url}) Actor.log.info(Pushed %d items to dataset, len(items)) # 潛在問題 Actor.log.warning(Input validation failed, using defaults) # 實際錯誤 Actor.log.error(Failed to fetch page, extra{url: url}) # 捕獲的異常帶堆棧 try: ... except Exception as exc: Actor.log.exception(exc, Unexpected error in handler) await Actor.exit()級別選擇的最佳實踐PythonPython 側(cè)的準則與 JS/TS 完全對齊Actor.log.debug()函數(shù)內(nèi)部的詳細操作級診斷Actor.log.info()一般性信息如 API 請求、成功操作Actor.log.warning()潛在問題場景校驗失敗、意外狀態(tài)Actor.log.error()實際發(fā)生的錯誤與失敗Actor.log.exception()被捕獲、需要保留堆棧信息的異常。日志與 Actor 本地調(diào)試apify run的正確打開方式日志能力只有接入了正確的運行流程才真正可用。apify-actor-development技能強調(diào)本地測試必須使用apify run而不是npm start、npm run start、yarn start等包管理器命令——后者不會正確配置 Apify 的環(huán)境與存儲日志輸出與存儲行為都會與平臺不一致。本地運行的基本流程參見 SKILL.mdapify run # 本地運行 Actor正確配置 Apify 環(huán)境與存儲本地運行時輸入數(shù)據(jù)需要放置于storage/key_value_stores/default/INPUT.json該文件內(nèi)容應(yīng)遵循.actor/input_schema.json定義的輸入?yún)?shù)結(jié)構(gòu)Actor 會像在平臺上一樣讀取它。在排障時要牢記一個重要事實apify run產(chǎn)生的所有數(shù)據(jù)datasets、key-value stores、request queues只存在于本地storage/目錄絕不會自動同步到 Apify Console。因此驗證本地運行結(jié)果時不要依賴 Apify Console而應(yīng)直接檢查本地storage/目錄或查看 Actor 的日志輸出——這正是日志規(guī)范在本地調(diào)試環(huán)節(jié)的用武之地一份分級合理、脫敏到位的日志可以讓你在不查存儲文件的情況下快速定位問題。技能文檔還提示實現(xiàn)日志與運行邏輯前需檢查.actor/actor.json中的usesStandbyMode配置僅當其值為true時才需要實現(xiàn) standby 模式的 readiness probe詳見 references/standby-mode.md。日志規(guī)范與 Actor 安全最佳實踐的聯(lián)動將日志參考文檔與技能主文檔的安全章節(jié)對照閱讀可以形成一套完整的防護閉環(huán)憑據(jù)隔離APIFY_TOKEN等密鑰絕不能出現(xiàn)在請求處理器或數(shù)據(jù)處理代碼中技能文檔明確要求使用 Apify SDK 內(nèi)置的憑據(jù)管理而不是在數(shù)據(jù)處理代碼里通過環(huán)境變量傳遞 Token在此基礎(chǔ)上日志器的脫敏邏輯作為第二道防線兜底防止憑據(jù)進入日志。登錄安全CLI 認證優(yōu)先使用環(huán)境變量APIFY_TOKEN或交互式apify login避免以命令行參數(shù)形式傳 Token參數(shù)會出現(xiàn)在進程列表中且可能被記錄進 shell 歷史。相關(guān)命令見 SKILL.md 的 Commands 一節(jié)。禁止繞過日志器console.log()/print()會繞過憑據(jù)脫敏屬于明確禁止的行為。日志作為本地排障主通道由于本地存儲不同步 Console本地運行時的日志輸出是驗證apify run結(jié)果的最直接手段之一。倉庫內(nèi)相關(guān)參考文檔索引apify-actor-development技能在倉庫內(nèi)以主文檔 引用文檔的方式組織與本主題直接相關(guān)及可延伸閱讀的路徑如下日志參考本文主體references/logging.md技能主文檔含安全、最佳實踐、本地測試、命令SKILL.mdActor 配置actor.json含usesStandbyMode等與運行行為相關(guān)的字段references/actor-json.mdStandby 模式與 readiness probe 實現(xiàn)references/standby-mode.md輸入 Schema 定義references/input-schema.md輸出 / 數(shù)據(jù)集 / KV 存儲 Schemareferences/output-schema.md、references/dataset-schema.md、references/key-value-store-schema.md說明以上路徑對應(yīng)agentic-awesome-skills-claude插件下的技能副本同一技能在agentic-awesome-skills插件下亦有結(jié)構(gòu)一致的副本如 SKILL.md兩處日志參考內(nèi)容保持一致。小結(jié)Apify Actor 的日志規(guī)范可以濃縮為三句話必須使用apify/logJS/TS或Actor.logPython日志器因為它們是憑據(jù)脫敏的第一道也是最后一道防線按級別分層輸出debug 埋細節(jié)、info 報過程、warning 標隱患、error/exception 報故障、外加 warningOnce/perf/deprecated/softFail/internal 等專用通道始終通過apify run本地驗證并以日志作為排障依據(jù)同時避免任何繞過日志器的console.log()/print()輸出。遵循這套規(guī)范Actor 的日志既安全又高效能夠在本地與平臺兩端提供一致、可檢索、可引用的運行證據(jù)。【免費下載鏈接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.項目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Agentic Awesome Skills 實戰(zhàn)指南：Apify Actor 日志系統(tǒng)深度解析（apify/log 與 Actor.log 全級別使用規(guī)范）
Agentic Awesome Skills 實戰(zhàn)指南Apify Actor 日志系統(tǒng)深度解析apify/log 與 Actor.log 全級別使用規(guī)范【免費下載鏈接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.項目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills導(dǎo)讀本文以 agentic-awesome-skills 倉庫內(nèi)apify-actor-development技能的官方日志參考文檔為主體系統(tǒng)講解 Apify Actor 在 JavaScript/TypeScript 與 Python 兩大技術(shù)棧下的日志規(guī)范為什么必須使用apify/log包與Actor.log日志器它們提供的全部日志級別各自適用于什么場景以及如何通過正確的日志實踐避免憑據(jù)泄露、提升可觀測性。讀完本文你將掌握一套可直接應(yīng)用于 Actor 開發(fā)全流程本地調(diào)試、平臺運行、排障定位的安全日志方案并能對照倉庫源碼級參考文檔快速檢索細節(jié)。為什么 Actor 日志必須走專用日志器安全是第一優(yōu)先級在 Apify Actor 開發(fā)中日志絕不只是把信息打印出來。apify-actor-development技能的日志參考文檔 references/logging.md 在開篇就以加粗形式給出了一條硬性規(guī)定JavaScript / TypeScript必須使用apify/log包Python必須使用Actor.log日志器。其核心原因在于這兩個日志器內(nèi)置了關(guān)鍵的安全脫敏邏輯critical security logic能夠自動審查并隱藏日志中的敏感數(shù)據(jù)——包括 Apify Token、API Key、憑據(jù)等從而防止它們在運行日志中被意外暴露。對應(yīng)的技能主文檔 SKILL.md 從正反兩面強化了這一要求最佳實踐清單Do中明確Always useapify/logpackage— censors sensitive data (API keys, tokens, credentials)禁止清單Dont中明確不要用console.log()或print()代替 Apify 日志器——它們會繞過憑據(jù)脫敏機制。這意味著如果 Actor 代碼里殘留了console.log()/print()一旦日志中包含 Token 或憑據(jù)就會以明文形式進入日志流可能在 Apify Console、第三方日志采集系統(tǒng)中被留存和擴散。因此使用專用日志器在 Apify 生態(tài)中首先是安全實踐其次才是可觀測性實踐。JavaScript / TypeScriptapify/log的十個日志級別在 JS/TS 技術(shù)棧中apify/log包提供了 10 個日志方法覆蓋從最詳細的調(diào)試信息到系統(tǒng)內(nèi)部消息的完整梯度。下表完整繼承自參考文檔日志方法級別定位適用場景l(fā)og.debug()調(diào)試級詳細的診斷信息用于函數(shù)內(nèi)部的細粒度追蹤log.info()信息級一般性提示消息如 API 請求、成功操作log.warning()警告級潛在問題場景如校驗失敗、意外狀態(tài)log.warningOnce()去重警告相同警告消息只記錄一次防止日志刷屏log.error()錯誤級實際發(fā)生的錯誤與失敗log.exception()異常級捕獲到的帶堆棧信息的異常log.perf()性能級性能指標與耗時信息log.deprecated()棄用級關(guān)于已棄用代碼的警告log.softFail()軟失敗級不中斷執(zhí)行的非致命失敗如輸入校驗失敗、跳過的條目log.internal()內(nèi)部級系統(tǒng)/內(nèi)部消息JS/TS 典型用法示例基于上述級別定義一個規(guī)范的 Actor 日志調(diào)用大致如下import { log } from apify/log; // 函數(shù)內(nèi)部的細粒度診斷 log.debug(Processing item, { itemId, attempt }); // 一般性信息API 請求、成功操作 log.info(Requesting page, { url }); log.info(Successfully pushed items, { count }); // 潛在問題校驗失敗、意外狀態(tài) log.warning(Unexpected input format, using defaults); log.warningOnce(Rate limit approaching); // 同類警告只出現(xiàn)一次 // 實際錯誤 log.error(Failed to fetch page, { url, statusCode }); // 捕獲到的異常帶堆棧 try { // ... } catch (err) { log.exception(err, Unexpected error in handler); } // 性能計時 log.perf(Crawl duration, { seconds: elapsed }); // 棄用提示 log.deprecated(Option X is deprecated, use Y instead); // 非致命失敗輸入校驗失敗、跳過條目 log.softFail(Skipping item due to missing field, { itemId }); // 系統(tǒng)內(nèi)部消息 log.internal(Initializing actor runtime);級別選擇的最佳實踐JS/TS參考文檔給出了清晰的分級使用準則log.debug()用于函數(shù)內(nèi)部的詳細操作級診斷適合埋點在循環(huán)、數(shù)據(jù)處理等高頻路徑中僅在需要排障時可調(diào)高日志級別查看log.info()用于一般性信息如 API 請求發(fā)出、操作成功完成log.warning()用于可能出問題的情況如校驗失敗、出現(xiàn)非預(yù)期狀態(tài)程序仍能繼續(xù)運行l(wèi)og.error()用于真正發(fā)生的錯誤與失敗log.exception()用于被try/catch捕獲、需要保留堆棧信息的異常。合理運用這套分級可以讓日志在信息充分與信噪比可控之間取得平衡常態(tài)下以info為基線排障時通過debug獲取細節(jié)warning/error則在 Console 中形成清晰的告警信號。PythonActor.log的日志級別在 Python 技術(shù)棧中Apify Actor 日志器Actor.log同樣內(nèi)置憑據(jù)脫敏邏輯且必須使用Actor.log而非 Python 內(nèi)置的print()。參考文檔列出 5 個日志方法日志方法級別定位適用場景Actor.log.debug()調(diào)試級詳細診斷信息用于函數(shù)內(nèi)部Actor.log.info()信息級一般性提示消息如 API 請求、成功操作Actor.log.warning()警告級潛在問題如校驗失敗、意外狀態(tài)Actor.log.error()錯誤級實際錯誤與失敗Actor.log.exception()異常級帶堆棧信息的異常Python 典型用法示例from apify import Actor async def main(): await Actor.init() # 函數(shù)內(nèi)部診斷 Actor.log.debug(Processing item, extra{item_id: item_id}) # 一般性信息 Actor.log.info(Fetching page, extra{url: url}) Actor.log.info(Pushed %d items to dataset, len(items)) # 潛在問題 Actor.log.warning(Input validation failed, using defaults) # 實際錯誤 Actor.log.error(Failed to fetch page, extra{url: url}) # 捕獲的異常帶堆棧 try: ... except Exception as exc: Actor.log.exception(exc, Unexpected error in handler) await Actor.exit()級別選擇的最佳實踐PythonPython 側(cè)的準則與 JS/TS 完全對齊Actor.log.debug()函數(shù)內(nèi)部的詳細操作級診斷Actor.log.info()一般性信息如 API 請求、成功操作Actor.log.warning()潛在問題場景校驗失敗、意外狀態(tài)Actor.log.error()實際發(fā)生的錯誤與失敗Actor.log.exception()被捕獲、需要保留堆棧信息的異常。日志與 Actor 本地調(diào)試apify run的正確打開方式日志能力只有接入了正確的運行流程才真正可用。apify-actor-development技能強調(diào)本地測試必須使用apify run而不是npm start、npm run start、yarn start等包管理器命令——后者不會正確配置 Apify 的環(huán)境與存儲日志輸出與存儲行為都會與平臺不一致。本地運行的基本流程參見 SKILL.mdapify run # 本地運行 Actor正確配置 Apify 環(huán)境與存儲本地運行時輸入數(shù)據(jù)需要放置于storage/key_value_stores/default/INPUT.json該文件內(nèi)容應(yīng)遵循.actor/input_schema.json定義的輸入?yún)?shù)結(jié)構(gòu)Actor 會像在平臺上一樣讀取它。在排障時要牢記一個重要事實apify run產(chǎn)生的所有數(shù)據(jù)datasets、key-value stores、request queues只存在于本地storage/目錄絕不會自動同步到 Apify Console。因此驗證本地運行結(jié)果時不要依賴 Apify Console而應(yīng)直接檢查本地storage/目錄或查看 Actor 的日志輸出——這正是日志規(guī)范在本地調(diào)試環(huán)節(jié)的用武之地一份分級合理、脫敏到位的日志可以讓你在不查存儲文件的情況下快速定位問題。技能文檔還提示實現(xiàn)日志與運行邏輯前需檢查.actor/actor.json中的usesStandbyMode配置僅當其值為true時才需要實現(xiàn) standby 模式的 readiness probe詳見 references/standby-mode.md。日志規(guī)范與 Actor 安全最佳實踐的聯(lián)動將日志參考文檔與技能主文檔的安全章節(jié)對照閱讀可以形成一套完整的防護閉環(huán)憑據(jù)隔離APIFY_TOKEN等密鑰絕不能出現(xiàn)在請求處理器或數(shù)據(jù)處理代碼中技能文檔明確要求使用 Apify SDK 內(nèi)置的憑據(jù)管理而不是在數(shù)據(jù)處理代碼里通過環(huán)境變量傳遞 Token在此基礎(chǔ)上日志器的脫敏邏輯作為第二道防線兜底防止憑據(jù)進入日志。登錄安全CLI 認證優(yōu)先使用環(huán)境變量APIFY_TOKEN或交互式apify login避免以命令行參數(shù)形式傳 Token參數(shù)會出現(xiàn)在進程列表中且可能被記錄進 shell 歷史。相關(guān)命令見 SKILL.md 的 Commands 一節(jié)。禁止繞過日志器console.log()/print()會繞過憑據(jù)脫敏屬于明確禁止的行為。日志作為本地排障主通道由于本地存儲不同步 Console本地運行時的日志輸出是驗證apify run結(jié)果的最直接手段之一。倉庫內(nèi)相關(guān)參考文檔索引apify-actor-development技能在倉庫內(nèi)以主文檔 引用文檔的方式組織與本主題直接相關(guān)及可延伸閱讀的路徑如下日志參考本文主體references/logging.md技能主文檔含安全、最佳實踐、本地測試、命令SKILL.mdActor 配置actor.json含usesStandbyMode等與運行行為相關(guān)的字段references/actor-json.mdStandby 模式與 readiness probe 實現(xiàn)references/standby-mode.md輸入 Schema 定義references/input-schema.md輸出 / 數(shù)據(jù)集 / KV 存儲 Schemareferences/output-schema.md、references/dataset-schema.md、references/key-value-store-schema.md說明以上路徑對應(yīng)agentic-awesome-skills-claude插件下的技能副本同一技能在agentic-awesome-skills插件下亦有結(jié)構(gòu)一致的副本如 SKILL.md兩處日志參考內(nèi)容保持一致。小結(jié)Apify Actor 的日志規(guī)范可以濃縮為三句話必須使用apify/logJS/TS或Actor.logPython日志器因為它們是憑據(jù)脫敏的第一道也是最后一道防線按級別分層輸出debug 埋細節(jié)、info 報過程、warning 標隱患、error/exception 報故障、外加 warningOnce/perf/deprecated/softFail/internal 等專用通道始終通過apify run本地驗證并以日志作為排障依據(jù)同時避免任何繞過日志器的console.log()/print()輸出。遵循這套規(guī)范Actor 的日志既安全又高效能夠在本地與平臺兩端提供一致、可檢索、可引用的運行證據(jù)。【免費下載鏈接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.項目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考