技术写作与文档2012trottercashion.com编辑精选
如何写好日志消息
How To Write Good Log Messages
导读
这篇讨论如何写出好的日志消息，评论集中在时间格式、上下文信息、日志级别和结构化/请求追踪。对写作者来说，日志是写给未来同事和运维的说明性写作：每条都要可排序、可检索、可关联。值得读，因为它训练你为读者补足上下文，并用格式减少歧义。
可以直接用的写作要点
- 01
时间戳统一用 YYYY-MM-DD（最好 UTC），让日志可排序且跨地区不产生日/月歧义。
- 02
每条日志都要补足上下文：谁、在哪、做了什么、对象是什么、结果如何，别只留一句孤立的报错。
- 03
严格区分日志级别，不要把 warning/error 当默认，给 debug/trace 留出空间，方便过滤噪声。
- 04
用结构化格式（如 JSON）和贯穿请求的 ID 关联同一次请求的多条日志，提升可检索和可追踪性。
HN 评论精选
日期格式应统一为 YYYY-MM-DD，保证可排序和跨地区可读。
像 08-08-2012-20:27:59 这样的时间戳，让人分不清哪个 08 是日、哪个是月；用 cut 取日期字段再 sort 后，也只能按（月、日、年）或（日、月、年）排序，跨多年时排序就失效。请用 YYYY-MM-DD，它可排序，对美国以外的人也直观，参见 ISO 8601。
shazow查看英文原文
"08-08-2012-20:27:59" Which 08 is the day or the month? cut -d ' ' -f2- foo.log | sort Great, now it's sorted by (month, day, year) or (day, month, year). If my logs span multiple years, the sorting is useless. Please use YYYY-MM-DD. It's sortable and more intuitive for everyone outside of the USA. See also http://en.wikipedia.org/wiki/ISO_8601
日志要提供足够上下文，并规范级别、滚动策略和文件头信息。
运维最难的是没有代码可看时判断应用在做什么；知道流程，但“failed to covert X at MyClass:44”这类信息上下文不够。日志级别也常被误用：开发者过度使用 warning/error，少用 debug/trace，噪声更难过滤。滚动日志应按事件（新一天、进程重启等）触发，而不是按 10MB 或 1k 行这类任意阈值；日志文件头至少写清版本号、用户和主机。生产环境的栈追踪即便有用，也不该放在主日志文件里。
3amOpsGuy查看英文原文
One of the hardest things in ops is trying to see what the app is doing without benefit of the code to review. I know what the app does, I know the process flows involved but 'failed to covert X at MyClass:44' doesn't have enough context for me. Also log levels - most developers over use warning and error levels and under uses debug and trace in my experience. It makes filtering out the noise harder. Rolling log files - roll on an event (new day, process bounced etc.) not on reaching a 10Mb limit or an equally arbitrary 1k lines limit. Use a header in the logfile, contain at least the version number of the code running, the user and host it is running on. Lastly stack traces, if they even have a use case at all in production, should not be in the main logfile.
时间戳用 UTC 加可排序格式，结构化日志（如 JSON）更利于处理。
UTC 适合做时间戳，但时间要可排序（YYYY-MM-DD）；制表符分隔字段有问题，除非转义日志数据里的制表符。这个格式很像 GELF。我现在很喜欢 JSON 日志：各种语言都能处理，还有工具能把过滤后的日志实时渲染到浏览器。
Pfhreak查看英文原文
UTC is great for timestamps, but he needs to make his times sortable (YYYY-MM-DD) Tab delimited fields are a problem, unless you escape the tabs inside the data you log. This format seems VERY similar to the Graylog Extended Log Format (or GELF) https://github.com/Graylog2/graylog2-docs/wiki/GELF I'm a huge fan of JSON logs now, having just finished implementing them on a major work project. Every language out there can take JSON in and do work against it, and there are some really awesome tools for rendering filtered logs to a browser in realtime.
用贯穿请求的 ID 给日志建立关联上下文，便于追踪一次请求的全过程。
这或许超出本文范围，但我在 Google 用过 Dapper：它用线程本地存储和 RPC 库插桩，把一个固定的 request-id 贯穿每次 RPC 调用和处理用户请求的线程。这样就能对请求处理代码透明地自动把 request ID 加进日志消息；可视化已记录的 RPC 时，也能把部分日志消息包含进去。
gwillen查看英文原文
This may be a bit out of scope for this post, but at Google I used to get a lot of mileage out of a system I worked on called Dapper: http://static.googleusercontent.com/external_content/untrusted_dlcp/research.google.com/en/us/pubs/archive/36356.pdf It uses thread-local storage and RPC library instrumentation to thread a fixed request-id through every RPC call and thread handling a particular user request. Then you can do things like automatically adding the request ID to log messages, transparently to the request-handling code. And when you visualize logged RPCs, you can include (some subset of) the logged messages in your visualization.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选