encore-logging

Encore.ts 结构化日志

对于需要结构化字段或追踪集成的应用事件，请使用 encore.dev/log。如果应用已有的字段名称和事件约定与本指南一致，请予以保留。

确定记录内容

为 Encore 无法从基础设施操作中推断的信息添加日志：

• 业务状态转换
• 决策及其依据
• 重试、回退和降级运行
• 决定重试、恢复还是中止的边界处发生的故障
• 需要领域上下文的外部系统交互
• 与安全相关或管理操作

Encore 已会追踪 API 请求、数据库查询、服务调用、缓存操作和 Pub/Sub 活动。不要用 request started、querying database 或 request completed 之类的日志来描述这些执行过程。

使用指标记录聚合计数和级别。使用追踪记录调用流程和耗时。使用日志记录调查单个事件所需的上下文。

输出结构化日志

保持消息稳定，并将可变数据放在字段中：

import log from "encore.dev/log";

log.info("order rejected", {
  event: "order.rejected",
  orderId,
  productId,
  reason: "insufficient_inventory",
  requestedQuantity,
  availableQuantity,
});

避免在消息中插入标识符。稳定的消息便于归类，而字段仍可搜索。

对于仪表板、告警或自动化会用到的事件，请包含稳定的 event 字段。优先采用 <domain>.<past-tense-event> 格式，例如 payment.authorized 或 subscription.cancelled。诊断日志不需要事件名称。

每个字段的名称和类型在不同事件中应保持一致。优先使用带明确单位的数值和类似枚举的值，而不是格式化文本：

log.info("payment authorized", {
  event: "payment.authorized",
  amountMinorUnits: 14900,
  currency: "SEK",
});

选择级别

• error：意外故障导致操作无法完成
• warn：应用已恢复，或在降级状态下继续运行
• info：有意义且频率相对较低的业务事件
• debug：正常运行不需要的诊断详情
• trace：高频内部状态

预期结果，例如验证失败、资源缺失、登录被拒或付款被拒，并不属于 error 事件。请根据其业务含义选择级别。

默认最低级别为 trace。在频繁执行的代码中添加 debug 或 trace 调用前，请先在 encore.app 中配置 log_level。

每个错误只记录一次

error 和 warn 的第一个参数可以是原始错误：

try {
  await chargeCustomer(customerId, amount);
} catch (err) {
  log.error(err, "payment authorization failed", {
    customerId,
    amountMinorUnits: amount,
    currency,
  });
  throw err;
}

传入原始错误可保留其类型、消息、堆栈跟踪和原因。将其转换为字符串会丢失这些信息。

应在拥有恢复决策权且具备足够领域上下文来描述影响的层级，记录已传播的故障。只有在较低层处理或抑制错误、重试、检测到不变量违反，或掌握传播过程中会丢失的上下文时，才应在该层记录日志。

添加共享上下文

如果同一领域操作中的多个事件共享字段，请使用 log.with()：

const logger = log.with({ importId, tenantId });

logger.info("user import completed", { succeededCount, failedCount });
logger.warn("user import row rejected", { rowNumber, reason: "invalid_email" });

Encore 已会将服务、端点、追踪 ID 和经过身份验证的用户 ID 附加到请求日志中。不要重复添加这些字段。

保护敏感数据

Encore 不会对日志字段进行脱敏。切勿记录凭据、令牌、会话标识符、Cookie、授权标头、机密配置、付款详情，或完整的请求和响应对象。

优先使用内部标识符，而非个人数据。如果关联操作需要使用不应存储的值，请使用稳定且不可逆的指纹。

sensitive API 选项会从追踪中脱敏请求和响应负载；但不会对传递给 log 的值进行脱敏。

控制日志量

通过结果、数量和耗时总结批量处理和长时间运行的操作。除非每项失败都需要调查，否则避免为每个项目单独记录一条日志。

对于大型值，只记录经过筛选的元数据，而非完整的提供方响应、记录、配置对象、数组或文档正文。限制预览内容的长度，并在记录前检查其中是否包含敏感数据。

检查现有应用时，优先查看循环、Pub/Sub 订阅者、中间件和频繁调用的辅助函数。这些调用点通常数量不多，却会产生大部分日志。

请参阅 Encore.ts 日志指南和 encore.dev/log API 参考。