better-logging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Turn important operations into durable structured records that answer "what happened?" with one query instead of a trail of log lines.

Treat the unit of instrumentation as an operation owned by the runtime, not as individual log statements sprinkled through the codebase.

将重要操作转换为持久化的结构化记录，只需一次查询就能回答“发生了什么？”，无需追踪一连串日志行。

将埋点的单元视为运行时所属的操作，而非分散在代码库中的单个日志语句。

bash

python3 scripts/audit_queryable_outcomes.py \
  --root . \
  --format markdown

Run the bundled

scripts/audit_queryable_outcomes.py

from this skill directory. If needed, resolve the directory containing this

SKILL.md

and pass the script path explicitly.

Read exactly one runtime reference before changing code:
- Electron, tRPC, IPC, background desktop jobs:
```
references/runtime-patterns-electron.md
```
- Node HTTP apps and workers:
```
references/runtime-patterns-node.md
```
Use
```
references/event-schema.md
```
to define the canonical event shape before writing middleware or wrappers.
Instrument the top 3 user-critical operations first. Do not start with every route or command in the repo.

bash

python3 scripts/audit_queryable_outcomes.py \
  --root . \
  --format markdown

从本skill目录运行内置的

scripts/audit_queryable_outcomes.py

脚本。如有需要，找到包含此

SKILL.md

的目录，并显式传入脚本路径。

Inventory operation boundaries. Transport boundaries usually matter most: HTTP handlers, tRPC procedures, IPC commands, queue consumers, cron jobs, startup flows. Treat low-level helper functions as enrichment points, not as the canonical operation.
Choose the operation record shape. Read
```
references/event-schema.md
```
. Lock required fields first: operation name, type, timestamps, duration, success, stable error code, correlation ID, version metadata.
Add one wrapper at the boundary. Start the record at entry. Enrich while the operation runs. Finalize and persist in
```
finally
```
so success and failure paths both emit an outcome.
Add domain context that improves debugging. Include actor, resource, trigger, rollout flags, retry count, and version data when available. Omit fields that are only interesting for local debugging or that contain secrets.
Persist or emit the result durably. Prefer a local table, operational event store, or queryable analytics sink. Do not rely on ephemeral console logs or in-memory buffers for critical outcomes.
Verify with real questions. Read
```
references/rollout-and-queries.md
```
. If the new shape cannot answer failure, latency, and regression questions quickly, the instrumentation is still too thin.

梳理操作边界。传输边界通常最为重要：HTTP处理器、tRPC过程、IPC命令、队列消费者、定时任务、启动流程。将底层辅助函数视为信息补充点，而非标准操作的载体。
选择操作记录格式。阅读
```
references/event-schema.md
```
。先锁定必填字段：操作名称、类型、时间戳、时长、成功状态、稳定错误码、关联ID、版本元数据。
在边界处添加包装器。在入口处初始化记录。在操作运行过程中补充信息。在
```
finally
```
块中完成记录并持久化，确保成功和失败路径都会输出结果。
添加有助于调试的领域上下文。尽可能包含参与者、资源、触发器、发布标记、重试次数和版本数据。省略仅对本地调试有用或包含敏感信息的字段。
持久化或可靠输出结果。优先选择本地表、操作事件存储或可查询的分析接收器。关键结果不要依赖临时控制台日志或内存缓冲区。
用实际问题验证。阅读
```
references/rollout-and-queries.md
```
。如果新格式无法快速回答故障、延迟和回归问题，说明埋点仍然不够完善。

Electron desktop app: Read
```
references/runtime-patterns-electron.md
```
for tRPC mutations,
```
ipcMain.handle
```
, startup actions, and background jobs.
Node server or worker: Read
```
references/runtime-patterns-node.md
```
for Express, Fastify, Hono-style handlers, queues, and cron jobs.

Electron桌面应用：针对tRPC变更、
```
ipcMain.handle
```
、启动操作和后台任务，请阅读
```
references/runtime-patterns-electron.md
```
。
Node服务器或工作进程：针对Express、Fastify、Hono风格的处理器、队列和定时任务，请阅读
```
references/runtime-patterns-node.md
```
。

Prefer one durable outcome event per important operation over many scattered log lines.
Keep
```
error_code
```
stable and machine-queryable. Treat free-form messages as secondary.
Record durations and retry counts on every critical operation.
Add correlation fields early. A missing
```
request_id
```
,
```
operation_id
```
, or
```
session_id
```
weakens every downstream query.
Separate operational truth from product analytics. Mirroring is fine; substitution is not.
Redact or hash secrets, tokens, raw prompts, user content, and full URLs when they are not strictly required.
Do not emit giant blobs by default. Persist pointers or summarized context instead.

```
scripts/audit_queryable_outcomes.py
```
Scan a repo for likely operation boundaries, existing instrumentation, correlation fields, and durable outcome signals.
```
references/event-schema.md
```
Required and recommended fields, naming guidance, and redaction rules.
```
references/runtime-patterns-electron.md
```
Boundary choices and wrapper patterns for Electron, tRPC, IPC, startup flows, and background jobs.
```
references/runtime-patterns-node.md
```
Boundary choices and wrapper patterns for HTTP apps, queue consumers, and cron jobs.
```
references/rollout-and-queries.md
```
Retrofit plan, acceptance checklist, and example questions the new instrumentation must answer.

```
scripts/audit_queryable_outcomes.py
```
扫描仓库，识别可能的操作边界、现有埋点、关联字段和持久化结果信号。
```
references/event-schema.md
```
必填和推荐字段、命名指南及编辑规则。
```
references/runtime-patterns-electron.md
```
Electron、tRPC、IPC、启动流程和后台任务的边界选择与包装器模式。
```
references/runtime-patterns-node.md
```
HTTP应用、队列消费者和定时任务的边界选择与包装器模式。
```
references/rollout-and-queries.md
```
改造计划、验收清单，以及新埋点必须能回答的示例问题。