Agentic Awesome Skills 实战指南Apify Actor 日志系统深度解析apify/log 与 Actor.log 全级别使用规范【免费下载链接】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导读本文以 agentic-awesome-skills 仓库内apify-actor-development技能的官方日志参考文档为主体系统讲解 Apify Actor 在 JavaScript/TypeScript 与 Python 两大技术栈下的日志规范为什么必须使用apify/log包与Actor.log日志器它们提供的全部日志级别各自适用于什么场景以及如何通过正确的日志实践避免凭据泄露、提升可观测性。读完本文你将掌握一套可直接应用于 Actor 开发全流程本地调试、平台运行、排障定位的安全日志方案并能对照仓库源码级参考文档快速检索细节。为什么 Actor 日志必须走专用日志器安全是第一优先级在 Apify Actor 开发中日志绝不只是把信息打印出来。apify-actor-development技能的日志参考文档 references/logging.md 在开篇就以加粗形式给出了一条硬性规定JavaScript / TypeScript必须使用apify/log包Python必须使用Actor.log日志器。其核心原因在于这两个日志器内置了关键的安全脱敏逻辑critical security logic能够自动审查并隐藏日志中的敏感数据——包括 Apify Token、API Key、凭据等从而防止它们在运行日志中被意外暴露。对应的技能主文档 SKILL.md 从正反两面强化了这一要求最佳实践清单Do中明确Always useapify/logpackage— censors sensitive data (API keys, tokens, credentials)禁止清单Dont中明确不要用console.log()或print()代替 Apify 日志器——它们会绕过凭据脱敏机制。这意味着如果 Actor 代码里残留了console.log()/print()一旦日志中包含 Token 或凭据就会以明文形式进入日志流可能在 Apify Console、第三方日志采集系统中被留存和扩散。因此使用专用日志器在 Apify 生态中首先是安全实践其次才是可观测性实践。JavaScript / TypeScriptapify/log的十个日志级别在 JS/TS 技术栈中apify/log包提供了 10 个日志方法覆盖从最详细的调试信息到系统内部消息的完整梯度。下表完整继承自参考文档日志方法级别定位适用场景log.debug()调试级详细的诊断信息用于函数内部的细粒度追踪log.info()信息级一般性提示消息如 API 请求、成功操作log.warning()警告级潜在问题场景如校验失败、意外状态log.warningOnce()去重警告相同警告消息只记录一次防止日志刷屏log.error()错误级实际发生的错误与失败log.exception()异常级捕获到的带堆栈信息的异常log.perf()性能级性能指标与耗时信息log.deprecated()弃用级关于已弃用代码的警告log.softFail()软失败级不中断执行的非致命失败如输入校验失败、跳过的条目log.internal()内部级系统/内部消息JS/TS 典型用法示例基于上述级别定义一个规范的 Actor 日志调用大致如下import { log } from apify/log; // 函数内部的细粒度诊断 log.debug(Processing item, { itemId, attempt }); // 一般性信息API 请求、成功操作 log.info(Requesting page, { url }); log.info(Successfully pushed items, { count }); // 潜在问题校验失败、意外状态 log.warning(Unexpected input format, using defaults); log.warningOnce(Rate limit approaching); // 同类警告只出现一次 // 实际错误 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 }); // 系统内部消息 log.internal(Initializing actor runtime);级别选择的最佳实践JS/TS参考文档给出了清晰的分级使用准则log.debug()用于函数内部的详细操作级诊断适合埋点在循环、数据处理等高频路径中仅在需要排障时可调高日志级别查看log.info()用于一般性信息如 API 请求发出、操作成功完成log.warning()用于可能出问题的情况如校验失败、出现非预期状态程序仍能继续运行log.error()用于真正发生的错误与失败log.exception()用于被try/catch捕获、需要保留堆栈信息的异常。合理运用这套分级可以让日志在信息充分与信噪比可控之间取得平衡常态下以info为基线排障时通过debug获取细节warning/error则在 Console 中形成清晰的告警信号。PythonActor.log的日志级别在 Python 技术栈中Apify Actor 日志器Actor.log同样内置凭据脱敏逻辑且必须使用Actor.log而非 Python 内置的print()。参考文档列出 5 个日志方法日志方法级别定位适用场景Actor.log.debug()调试级详细诊断信息用于函数内部Actor.log.info()信息级一般性提示消息如 API 请求、成功操作Actor.log.warning()警告级潜在问题如校验失败、意外状态Actor.log.error()错误级实际错误与失败Actor.log.exception()异常级带堆栈信息的异常Python 典型用法示例from apify import Actor async def main(): await Actor.init() # 函数内部诊断 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 侧的准则与 JS/TS 完全对齐Actor.log.debug()函数内部的详细操作级诊断Actor.log.info()一般性信息如 API 请求、成功操作Actor.log.warning()潜在问题场景校验失败、意外状态Actor.log.error()实际发生的错误与失败Actor.log.exception()被捕获、需要保留堆栈信息的异常。日志与 Actor 本地调试apify run的正确打开方式日志能力只有接入了正确的运行流程才真正可用。apify-actor-development技能强调本地测试必须使用apify run而不是npm start、npm run start、yarn start等包管理器命令——后者不会正确配置 Apify 的环境与存储日志输出与存储行为都会与平台不一致。本地运行的基本流程参见 SKILL.mdapify run # 本地运行 Actor正确配置 Apify 环境与存储本地运行时输入数据需要放置于storage/key_value_stores/default/INPUT.json该文件内容应遵循.actor/input_schema.json定义的输入参数结构Actor 会像在平台上一样读取它。在排障时要牢记一个重要事实apify run产生的所有数据datasets、key-value stores、request queues只存在于本地storage/目录绝不会自动同步到 Apify Console。因此验证本地运行结果时不要依赖 Apify Console而应直接检查本地storage/目录或查看 Actor 的日志输出——这正是日志规范在本地调试环节的用武之地一份分级合理、脱敏到位的日志可以让你在不查存储文件的情况下快速定位问题。技能文档还提示实现日志与运行逻辑前需检查.actor/actor.json中的usesStandbyMode配置仅当其值为true时才需要实现 standby 模式的 readiness probe详见 references/standby-mode.md。日志规范与 Actor 安全最佳实践的联动将日志参考文档与技能主文档的安全章节对照阅读可以形成一套完整的防护闭环凭据隔离APIFY_TOKEN等密钥绝不能出现在请求处理器或数据处理代码中技能文档明确要求使用 Apify SDK 内置的凭据管理而不是在数据处理代码里通过环境变量传递 Token在此基础上日志器的脱敏逻辑作为第二道防线兜底防止凭据进入日志。登录安全CLI 认证优先使用环境变量APIFY_TOKEN或交互式apify login避免以命令行参数形式传 Token参数会出现在进程列表中且可能被记录进 shell 历史。相关命令见 SKILL.md 的 Commands 一节。禁止绕过日志器console.log()/print()会绕过凭据脱敏属于明确禁止的行为。日志作为本地排障主通道由于本地存储不同步 Console本地运行时的日志输出是验证apify run结果的最直接手段之一。仓库内相关参考文档索引apify-actor-development技能在仓库内以主文档 引用文档的方式组织与本主题直接相关及可延伸阅读的路径如下日志参考本文主体references/logging.md技能主文档含安全、最佳实践、本地测试、命令SKILL.mdActor 配置actor.json含usesStandbyMode等与运行行为相关的字段references/actor-json.mdStandby 模式与 readiness probe 实现references/standby-mode.md输入 Schema 定义references/input-schema.md输出 / 数据集 / KV 存储 Schemareferences/output-schema.md、references/dataset-schema.md、references/key-value-store-schema.md说明以上路径对应agentic-awesome-skills-claude插件下的技能副本同一技能在agentic-awesome-skills插件下亦有结构一致的副本如 SKILL.md两处日志参考内容保持一致。小结Apify Actor 的日志规范可以浓缩为三句话必须使用apify/logJS/TS或Actor.logPython日志器因为它们是凭据脱敏的第一道也是最后一道防线按级别分层输出debug 埋细节、info 报过程、warning 标隐患、error/exception 报故障、外加 warningOnce/perf/deprecated/softFail/internal 等专用通道始终通过apify run本地验证并以日志作为排障依据同时避免任何绕过日志器的console.log()/print()输出。遵循这套规范Actor 的日志既安全又高效能够在本地与平台两端提供一致、可检索、可引用的运行证据。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
