Logging Best Practices

Logging Best Practices Skill

目的

本技能提供应用内日志的实践指南，聚焦 宽事件（canonical log lines）：每个请求、每个服务只发出一条富含上下文的日志事件，便于调试与分析。

适用场景

在以下情况参考本指南：

• 编写或审查日志代码
• 使用 console.log、logger.info 等
• 为新服务设计日志策略
• 搭建日志基础设施

核心原则

1. 宽事件（关键）

每个请求、每个服务只发一条富含上下文的日志事件。不要在 handler 里到处打 log，而是在请求结束时汇总为一条结构化事件再输出。

const wideEvent: Record = {
 method: 'POST',
 path: '/checkout',
 requestId: c.get('requestId'),
 timestamp: new Date().toISOString(),
};

try {
 const user = await getUser(c.get('userId'));
 wideEvent.user = { id: user.id, subscription: user.subscription };

 const cart = await getCart(user.id);
 wideEvent.cart = { total_cents: cart.total, item_count: cart.items.length };

 wideEvent.status_code = 200;
 wideEvent.outcome = 'success';
 return c.json({ success: true });
} catch (error) {
 wideEvent.status_code = 500;
 wideEvent.outcome = 'error';
 wideEvent.error = { message: error.message, type: error.name };
 throw error;
} finally {
 wideEvent.duration_ms = Date.now() - startTime;
 logger.info(wideEvent);
}