b2c-logs

B2C 日志技能

使用 b2c CLI 检索和监控 Salesforce B2C Commerce 实例上的日志文件。logs get 命令专为 Agent 友好的非交互式日志检索而设计，并提供结构化 JSON 输出。

提示： 如果未全局安装 b2c，请改用 npx @salesforce/b2c-cli（例如，npx @salesforce/b2c-cli logs get）。

配置与身份验证

CLI 会自动从 SFCC_* 环境变量（包括项目 .env）、所选的项目本地或共享 dw.json 以及配置插件中发现目标实例和凭据。package.json 仅提供非敏感默认值。通常无需使用 --server、--client-id、--client-secret、--username 和 --password 等标志——只有在需要覆盖自动检测到的值时才传入这些标志。

如果只配置了服务器，首次运行命令时会打开浏览器，让用户使用其 Account Manager 账户登录，并等待登录完成；请告知用户完成登录。用户的 Business Manager 角色决定其访问权限，403 错误会指出缺少的权限（例如 Cartridges 所需的 WebDAV_Manage_Customization）。

运行 b2c setup inspect 查看解析后的配置，以及每个值的来源（可使用 --json 进行脚本处理；默认情况下，密钥会保持隐藏）。有关优先级规则和故障排查，请参阅 b2c-cli:b2c-config 技能。

面向 Agent 的日志检索

logs get 命令针对编码 Agent 进行了优化：

• 检索日志后立即退出（非交互式）
• 支持使用 --json 输出结构化数据
• 可按时间、级别和文本搜索进行筛选
• 自动规范化文件路径，以便在 IDE 中点击打开

示例

获取最近的日志

# Get last 20 entries from error and customerror logs (default)
b2c logs get

# Get last 50 entries
b2c logs get --count 50

# JSON output for programmatic parsing
b2c logs get --json

按时间筛选

# Entries from the last 5 minutes
b2c logs get --since 5m

# Entries from the last 1 hour
b2c logs get --since 1h

# Entries from the last 2 days
b2c logs get --since 2d

# Entries after a specific time (ISO 8601)
b2c logs get --since "2026-01-25T10:00:00"

按日志级别筛选

# Only ERROR level entries
b2c logs get --level ERROR

# ERROR and FATAL entries
b2c logs get --level ERROR --level FATAL

搜索文本

# Search for "OrderMgr" in messages
b2c logs get --search OrderMgr

# Search for payment errors
b2c logs get --search "PaymentProcessor"

组合筛选条件

# Recent errors containing "PaymentProcessor"
b2c logs get --since 1h --level ERROR --search "PaymentProcessor" --json

# Last hour of errors and fatals from specific log types
b2c logs get --filter error --filter warn --since 1h --level ERROR --level FATAL

列出可用的日志文件

# List all log files
b2c logs list

# List specific log types
b2c logs list --filter error --filter customerror

# List logs in a subdirectory (path-like filter)
b2c logs list --filter internal/server

# JSON output
b2c logs list --json

实时跟踪日志（供人工使用）

用于交互式日志监控（不适用于 Agent）：

# Tail error and customerror logs
b2c logs tail

# Tail specific log types
b2c logs tail --filter debug --filter error

# Tail only ERROR and FATAL level entries
b2c logs tail --level ERROR --level FATAL

# Tail with text search
b2c logs tail --search "PaymentProcessor"

# Combined filtering
b2c logs tail --filter customerror --level ERROR --search "OrderMgr"

# Stop with Ctrl+C

下载完整日志文件

如需下载完整日志文件，请使用 JSON 输出中的 file 字段，并配合 b2c-cli:b2c-webdav：

b2c webdav get error-odspod-0-appserver-20260126.log --root=logs -o -

JSON 输出结构

使用 --json 时，logs get 会返回：

{
  "count": 1,
  "entries": [
    {
      "file": "error-odspod-0-appserver-20260126.log",
      "timestamp": "2026-01-26 04:38:03.022 GMT",
      "level": "ERROR",
      "message": "PipelineCallServlet|156679877|Sites-Site|...",
      "raw": "[2026-01-26 04:38:03.022 GMT] ERROR PipelineCallServlet|..."
    }
  ]
}

字段	说明
file	源日志文件名（可与 b2c-cli:b2c-webdav 配合使用，以下载完整文件）
level	日志级别：ERROR、WARN、INFO、DEBUG、FATAL、TRACE
timestamp	条目时间戳
message	日志消息（路径已规范化，以便在 IDE 中点击打开）
raw	未经处理的原始日志行

日志类型

常见的日志文件前缀：

前缀	描述
error	系统错误
customerror	自定义脚本错误（Logger.error()）
warn	警告
debug	调试输出（启用时）
info	信息性消息
jobs	作业执行日志
api	API 问题和违规
deprecation	已弃用的 API 用法
quota	配额警告

以上前缀对应的是内置日志文件。此外，任何通过_自定义日志类别_记录日志的脚本，都会将日志写入带有 custom- 前缀的专用文件——这与 customerror 不同。集成和作业代码（支付网关、ERP/OMS/CRM 同步、信息流和导入作业）几乎总是以这种方式记录日志，因此，排查问题时需要查看的条目通常位于 custom-* 文件中，而不是 error/customerror 中。

自定义日志文件名遵循以下模式：

custom-<prefix>-<hostname>-appserver-<date>.log

<prefix> 部分是发出日志的代码传给 Logger.getLogger(prefix, category) 的第一个参数，因此可通过日志文件直接找到写入日志的代码：

代码	日志文件	读取时使用的筛选条件
Logger.getLogger('PaymentProcessor', 'payment')	custom-PaymentProcessor-*.log	--filter custom-PaymentProcessor
Logger.getLogger('PimTaxImport', 'tax')	custom-PimTaxImport-*.log	--filter custom-PimTaxImport
Logger.getLogger('orderexport', 'export')	custom-orderexport-*.log	--filter custom-orderexport

（第二个参数是日志_类别_，用于配置；它不会出现在文件名中。）关于如何创建这些日志记录器，请参阅 b2c:b2c-logging 技能。

注意： --filter 会对文件的日志类别进行前缀（以此开头）匹配，而非精确匹配——因此，--filter custom- 会遍历所有 custom-* 文件，而 --filter custom-Payment 也会匹配 custom-PaymentProcessor。筛选条件也会匹配文件名的开头。类别在_第二个_连字符处截断，因此名为 custom-payment-gateway-*.log 的文件，其类别为 custom-payment，但 --filter custom-payment-gateway 仍会通过文件名选中它。若要读取某个特定的自定义日志，请按其日志记录器名称筛选（例如 --filter custom-PimTaxImport）；若要遍历所有日志，请使用 --filter custom-。--filter 会替换默认的 error/customerror 集合，而不是在其上追加；如果 b2c logs get 找不到条目，则会列出已存在的 custom-* 日志。

查找自定义日志文件

由于默认的 error/customerror 检索不会包含自定义日志文件，因此在调查集成或作业时，请主动查找这些文件：

# 1. Enumerate all log files, or narrow to just custom ones
b2c logs list
b2c logs list --filter custom

# 2. Scan the output for an unfamiliar custom-* prefix whose size or
#    last-modified time grew when the incident started, then read it
b2c logs get --filter custom-PimTaxImport --since 1h

# 3. Read all custom logs at once when you don't yet know the prefix
b2c logs get --filter custom-

b2c logs list 会报告每个文件的大小和最后修改时间戳，这是快速发现事故期间产生大量日志的自定义日志记录器的最佳方式。找到前缀后，使用 --filter custom-<prefix>（或直接使用 --filter custom- 遍历所有日志）读取日志条目。

如果 logs list 的输出不完整，或者你想确认实例上的原始 *.log 文件名，请改用 WebDAV：

# Enumerate log filenames directly over WebDAV
b2c webdav ls --root logs

子目录中的日志

Logs/ 目录包含 internal/ 等子目录（例如 server、ccp、health、csrf-violations、internalquota）。默认情况下不会列出这些子目录。要访问它们，请传入路径形式的 --filter（其中包含 /）：工具会递归进入该子目录，并根据相对于 Logs/ 的路径匹配文件。

# All "server" logs under internal/
b2c logs list --filter internal/server

# Everything under internal/ (trailing slash)
b2c logs tail --filter internal/

# Mix a subdirectory filter with normal prefix filters
b2c logs get --filter error --filter internal/server

此功能在 logs list、logs get 和 logs tail（以及对应的 MCP 工具）中的工作方式相同。

更多命令

请参阅 b2c logs --help，了解所有可用命令和选项。

相关技能

• b2c-cli:b2c-webdav - 直接通过 WebDAV 访问文件，以下载完整日志文件
• b2c-cli:b2c-config - 验证配置和凭据
• b2c:b2c-logging - 编写端：了解服务器端代码如何创建生成 custom-* 日志文件的自定义日志类别