Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

logging/overview.md and logging/api.md document contradictory hdb.log entry formats

オープン
  • 何か問題がありますか？
#657 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 2 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
52/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
活発
技術スタック
typescript
領域
documentation, observability

調査の方向性

まず、utility/logging/harper_logger.ts:778 にログエントリを構築する呼び出し元をたどるか、実行中のインスタンスからサンプルを取得します。結果を reference/logging/overview.md および reference/logging/api.md と比較し、tags と TaggedLogger の形式も確認してから、編集する前に v4 のコピーを確認します。ドキュメント化された形式が emitter と一致し、1 ページが正規形式を所有していれば完了です。

索引モデルが issue の本文から書いたものです。

説明

content
What's wrong

Two reference pages document the hdb.log entry format with different field orders, and both present it as "the standard format." One of them is wrong.

Page Documented format
reference/logging/overview.md:26 <timestamp> [<thread>/<id>] [<level>] ...[<tags>]: <message>
reference/logging/api.md:128 <timestamp> [<level>] [<thread>/<id>]: <message>

overview.md puts thread before level; api.md puts level before thread. overview.md also documents a trailing [<tags>] field that api.md omits entirely, and its worked example at :32 follows its own ordering:

2023-03-09T14:25:05.269Z [main/0] [notify]: HarperDB successfully started.

api.md:134 additionally gives a distinct TaggedLogger form, <timestamp> [<level>] [<tag>]: <message>, with no thread field — which may be correct, may be a third variant, or may just be the same disagreement again.

Which one is right

Not determined. I traced the emitter as far as utility/logging/harper_logger.ts:778:

function logToFile(log) {
	let entry = `${new Date().toISOString()} ${log}${log.endsWith('\n') ? '' : '\n'}`;

That prepends only the ISO timestamp — every bracketed field is assembled by callers upstream, so the ordering is not visible at this layer. Settling it needs either a sample from a running instance or a trace of the call sites that build log. That is step one for whoever picks this up; please do not resolve it by picking the more plausible-looking page.

Also worth confirming while there: whether [<tags>] still exists as a field, and whether the TaggedLogger form genuinely drops the thread or whether that is the same error a third time.

Why this is worth fixing beyond the inconsistency

This is not only a reader-facing problem. Both files are declared whole-file sources for the logging rule in @harperfast/skills:

- path: reference/v5/logging/overview.md
  role: primary
- path: reference/v5/logging/api.md
  role: primary

The generator concatenates both and hands them to the model as one undifferentiated block with no per-source labels. Faced with two contradictory formats, it silently emitted only api.md's ordering and dropped overview.md's tags field, its worked example, and its field table (thread/id values main/http/job; tags values custom-function/auth-event). The generated rule's own "When to Use" advertises helping an agent "understand the log entry format."

Nothing flags this. validate-generated.mjs passes — it checks structure (manifest consistency, frontmatter, sourceCommit/inputHash, AGENTS.md round-trip, source-exists, byte-identical slices), not agreement between sources. So a contradiction in our docs is laundered into agent-facing rules with no signal, and whichever page the model happens to favor becomes the one agents act on.

The skills-side manifest cannot fix this. A generator can pick one of two contradictory inputs, but it cannot know which is true.

Suggested fix
  1. Determine the actual emitted format (live sample or trace the callers of logToFile).
  2. Correct whichever page is wrong, and reconcile the [<tags>] field and the TaggedLogger variant.
  3. Prefer having one page own the format and the other link to it, rather than restating it. Two independent statements of the same format is what produced this.
  4. Check the v4 versioned copies under reference_versioned_docs/version-v4/ against a v4 harper ref before touching them — do not assume v4 matches v5.
How this surfaced

Found during a coverage audit of docs-driven skill rule generation, which was itself prompted by a confirmed content loss in a different rule (HarperFast/skills#81). This one is a distinct failure mode: not material dropped for lack of an anchor, but two sources disagreeing and the disagreement being resolved silently.

sent with Claude Opus 5

主要言語
MDX
スター
9
フォーク
9
平均マージ
1日 20時間
マージ済み PR（30日）
16

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

HarperFast/documentation のほかの issue

HarperFast/documentation の issue をすべて見る

似ている issue

Documentation の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。