Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#657 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
52/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
typescript
Área
documentation, observability

Línea de trabajo

Empieza rastreando los llamadores que construyen entradas de log en utility/logging/harper_logger.ts:778, o captura una muestra de una instancia en ejecución. Compara el resultado con reference/logging/overview.md y reference/logging/api.md, incluidas las formas de tags y TaggedLogger, y comprueba después las copias de v4 antes de editar. Se considera terminado cuando los formatos documentados coinciden con el emisor y una página contiene el formato canónico.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
MDX
Estrellas
9
Forks
9
Merge medio
2 d 23 h
PR fusionados (30 d)
26

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de HarperFast/documentation

Todos los issues de HarperFast/documentation

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.