encore-go-logging

Encore.go 结构化日志记录

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

决定记录什么

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

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

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

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

输出结构化日志

保持消息稳定，并在消息后传入交替排列的字符串键和值：

import "encore.dev/rlog"

rlog.Info("order rejected",
	"event", "order.rejected",
	"order_id", orderID,
	"product_id", productID,
	"reason", "insufficient_inventory",
	"requested_quantity", requestedQuantity,
	"available_quantity", availableQuantity,
)

避免将标识符插入消息中。稳定的消息便于分组，而字段可供搜索。

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

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

rlog.Info("payment authorized",
	"event", "payment.authorized",
	"amount_minor_units", 14900,
	"currency", "SEK",
)

Encore 的运行时字段使用 snake_case。以 encore_ 开头的字段名称为保留名称；rlog 会为其添加 x_ 前缀。

选择日志级别

Encore.go 提供 Error、Warn、Info 和 Debug。它不会通过 rlog 提供 Trace 函数。

• Error：意外失败导致操作无法完成
• Warn：应用已恢复，或在降级状态下继续运行
• Info：有意义且频率相对较低的业务事件
• Debug：正常运行不需要的诊断细节

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

默认最低级别为 trace，因此所有四种 rlog 级别都会输出。在频繁执行的代码中添加 Debug 调用前，请先在 encore.app 中配置 log_level。

每个错误只记录一次

将原始 error 作为字段值传入：

if err := chargeCustomer(ctx, customerID, amount); err != nil {
	rlog.Error("payment authorization failed",
		"err", err,
		"customer_id", customerID,
		"amount_minor_units", amount,
		"currency", currency,
	)
	return err
}

传入 error 值可让 rlog 应用其错误序列化逻辑。如果先调用 err.Error()，传入的就只是普通字符串。

在负责恢复决策且拥有足够业务上下文来描述影响的层记录返回的失败。只有在较低层处理或抑制错误、进行重试、检测到不变量违反，或掌握返回错误中不包含的上下文时，才应在该层记录日志。

添加共享上下文

如果同一业务操作中的多个事件共享字段，请使用 rlog.With：

logger := rlog.With("import_id", importID, "tenant_id", tenantID)

logger.Info("user import completed", "succeeded_count", succeededCount, "failed_count", failedCount)
logger.Warn("user import row rejected", "row_number", rowNumber, "reason", "invalid_email")

Encore 已经会在请求日志中附加服务、端点、跟踪 ID 和已认证用户 ID。请勿重复添加这些信息。

保护敏感数据

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

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

sensitive API 注解和 encore:"sensitive" 结构体标签会对跟踪中的请求和响应负载进行脱敏；它们不会对传入 rlog 的值进行脱敏。

控制日志量

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

对于较大的值，只记录选定的元数据，而不是完整的提供方响应、记录、配置值、切片或文档正文。限制预览内容，并在记录前检查其中是否包含敏感数据。

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

请参阅 Encore.go 日志指南和 rlog 包参考。