用途:在编写、评审或重构服务日志时,把日志从散落的人类可读字符串改造成可观测性原语——每个工作单元(HTTP 请求、队列消息、cron 触发、CLI 调用)只发出一条上下文丰富的结构化事件。
主要能力:提供编排流程(先识别运行时、审计现有日志配置与调用点、确定工作单元,再按“日志配置→规范中间件→注解助手→迁移旧调用”的顺序实施并验证);强制四类上下文(身份、环境、业务、性能与结果);覆盖高基数与高维度字段设计、与 OpenTelemetry span 关联、字段命名稳定、JSON 单行输出到 stdout、仅用 info/error 两级、抛出前只记录一次等原则;附反模式对照表(字符串插值、散落逐步日志、print 残留、只记低基数、记录原始路径、每文件新建 logger、随机 1% 采样、记录完整请求响应体等)。
使用方式:按运行时加载对应参考——Python 服务(FastAPI、Starlette、Django、Flask、Celery、脚本)用 references/python.md 及 scripts/canonical_asgi.py;Cloudflare Workers 用 references/cloudflare-workers.md;采样策略用 references/sampling.md;未覆盖技术栈以最接近的参考为模板,替换惯用库与框架钩子。
适用场景:新服务日志设计、排查会话、单条日志的增补,以及“健康检查刷屏”等小任务。
限制:具体收费、价格、平台与效果资料未提供;正确性依赖各运行时参考文件,未加载就写代码易误用平台特性(如 Workers 上把 waitUntil 当日志出口、Python BaseHTTPMiddleware 丢失 contextvars)。