mcpField
L
logging-best-practices

logging-best-practices

github.com/ncklrs开发53140 次安装35 周前更新
代码仓库

关于 logging-best-practices

为开发和运维团队提供生产级日志实践指导的 Skill，适用于日志设计、代码审查和生产故障排查。它侧重于每个请求生成包含丰富上下文的结构化事件，以便后续查询。

主要功能

  1. 01每个请求生成宽事件日志
  2. 02高基数字段设计指导
  3. 03基于结果的采样策略
  4. 04识别现有日志反模式
  5. 05以查询需求指导日志架构

适用场景

  1. 01为新服务设计日志
  2. 02审查代码中的日志语句
  3. 03排查生产环境故障
  4. 04迁移到结构化日志并减少日志量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ncklrs/startup-os-skills --skill logging-best-practices

安装后在 Claude Code 中输入/logging-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

metadata.json
rules/
_sections.md
antipattern-otel-silver-bullet.md
antipattern-scattered-logs.md
antipattern-string-search.md
architecture-event-lifecycle.md
architecture-wide-events.md
fields-business-context.md
fields-high-cardinality.md
fields-required-context.md
sampling-always-keep.md
sampling-tail-sampling.md

详细介绍

日志记录最佳实践

基于 Boris Tane 的 loggingsucks.com 理念，为生产级日志记录提供专家指导。

核心理念

不要再记录“代码正在做什么”，开始记录“此请求发生了什么”。

传统日志记录针对写入进行了优化，而非查询。开发者为了方便即时调试而输出日志，却不考虑之后如何搜索。这会在规模扩大时造成巨大的信噪比问题。

宽事件架构

不要在代码中零散地写日志语句，而应为每项服务的每个请求构建一个全面的事件：

// ❌ Traditional scattered logging
logger.info("Request started");
logger.info(`User ${userId} found`);
logger.info("Fetching cart");
logger.debug(`Cart has ${items.length} items`);
logger.info("Processing payment");
logger.error(`Payment failed: ${error.message}`);

// ✅ Wide event - build throughout request, emit once
const event = {
  request_id: req.id,
  timestamp: Date.now(),
  service: "checkout",
  version: "2.3.1",

  user: { id: userId, tier: "premium", account_age_days: 847 },
  cart: { id: cartId, item_count: 3, total_cents: 15999 },
  payment: { method: "card", provider: "stripe", latency_ms: 234 },

  outcome: "failure",
  error: { type: "PaymentDeclined", code: "card_declined", retriable: true }
};

logger.info(event);

核心概念

概念定义
宽事件每项服务针对每个请求记录一条全面且包含丰富上下文的日志
基数唯一值的数量（用户 ID = 高，HTTP 方法 = 低）
维度每个事件包含的字段数（目标是 40 个以上有意义的字段）
尾部采样请求完成后，根据结果决定是否采样

何时应用此技能

  • 在新服务中实现日志记录
  • 审查包含日志语句的代码
  • 调试生产环境问题
  • 设计可观测性策略
  • 从 printf 风格迁移到结构化日志记录
  • 在提升可查询性的同时减少日志量

此技能提供的内容

  1. 面向不同框架和语言的宽事件模式
  2. 面向高基数调试的字段设计指导
  3. 保留有效信号的采样策略
  4. 检测现有日志代码中的反模式
  5. 面向日志架构的查询优先思维

评论

支持 Markdown