Structured Logging Standards
Requirements
- Use
log/slog exclusively
- Never use
log.Printf(), fmt.Print(), or visual formatting (===, empty lines)
- Use structured fields, not string interpolation
- Single format: JSON to stdout
// Wrong
logger.Printf("WARNING: Failed to fetch %s", url)
// Right
slog.Warn("upstream fetch failed", "upstream", url, "error", err)
Setup
cooked uses a single JSON handler writing to stdout:
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
}))
slog.SetDefault(logger)
No log streams, no OTel/ECS formats, no object storage — just structured JSON to stdout.
Request Log Example
Every request is logged with structured fields:
{
"time": "2026-02-06T12:00:00Z",
"level": "INFO",
"msg": "request",
"method": "GET",
"path": "/https://cgit.internal/repo/plain/README.md",
"upstream": "https://cgit.internal/repo/plain/README.md",
"status": 200,
"cache": "hit",
"upstream_ms": 0,
"render_ms": 12,
"total_ms": 14,
"content_type": "markdown",
"bytes": 14832
}
Cache field values: hit, miss, revalidated, expired.
Log Message Style Guide
| Rule |
Guideline |
Example |
| Tense |
Past for events, present for conditions |
upstream fetched, cache full |
| Case |
lowercase start (no capital unless proper noun) |
config loaded, mermaid block found |
| Punctuation |
No trailing period (fragments, not sentences) |
request completed not Request completed. |
| Redundancy |
No severity prefix (level conveys this) |
upstream unreachable not Error: upstream unreachable |
| Specificity |
State what failed, not generic failure |
upstream fetch failed not operation failed |
| Brevity |
Omit articles and filler words |
file too large not The file was too large |
| Action |
Use verb-noun or noun-verb pattern |
config loaded, invalid upstream url |
Severity Levels
| Level |
When to use |
Examples |
| ERROR |
Unrecoverable failures requiring attention |
template parse failed, listen failed |
| WARN |
Degraded but recoverable situations |
upstream returned 5xx, cache eviction failed |
| INFO |
Normal business events |
request, server started, config loaded |
| DEBUG |
Internal details for troubleshooting |
cache hit, rewriting relative url, mdx import stripped |
Structured Fields
- Use snake_case for field names:
upstream_ms, content_type, cache_status
- Suffix units:
_ms, _bytes, _count
- Boolean fields:
has_mermaid, has_toc
- Avoid embedding data in message string; use fields instead
// Bad
slog.Info(fmt.Sprintf("fetched %s in %dms", url, dur))
// Good
slog.Info("upstream fetched", "upstream", url, "duration_ms", dur)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: logging-config3description: MANDATORY - All logging must use slog with structured JSON fields. Covers log/slog setup, structured logging, log levels, request logging, log message style, field naming. Load before writing any slog, log, or fmt.Print logging code. Use when this capability is needed.4---56# Structured Logging Standards78## Requirements910- Use `log/slog` exclusively11- Never use `log.Printf()`, `fmt.Print()`, or visual formatting (`===`, empty lines)12- Use structured fields, not string interpolation13- Single format: JSON to stdout1415```go16// Wrong17logger.Printf("WARNING: Failed to fetch %s", url)1819// Right20slog.Warn("upstream fetch failed", "upstream", url, "error", err)21```2223---2425## Setup2627cooked uses a single JSON handler writing to stdout:2829```go30logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{31 Level: slog.LevelInfo,32}))33slog.SetDefault(logger)34```3536No log streams, no OTel/ECS formats, no object storage — just structured JSON to stdout.3738---3940## Request Log Example4142Every request is logged with structured fields:4344```json45{46 "time": "2026-02-06T12:00:00Z",47 "level": "INFO",48 "msg": "request",49 "method": "GET",50 "path": "/https://cgit.internal/repo/plain/README.md",51 "upstream": "https://cgit.internal/repo/plain/README.md",52 "status": 200,53 "cache": "hit",54 "upstream_ms": 0,55 "render_ms": 12,56 "total_ms": 14,57 "content_type": "markdown",58 "bytes": 1483259}60```6162Cache field values: `hit`, `miss`, `revalidated`, `expired`.6364---6566## Log Message Style Guide6768| Rule | Guideline | Example |69|------|-----------|---------|70| Tense | Past for events, present for conditions | `upstream fetched`, `cache full` |71| Case | lowercase start (no capital unless proper noun) | `config loaded`, `mermaid block found` |72| Punctuation | No trailing period (fragments, not sentences) | `request completed` not `Request completed.` |73| Redundancy | No severity prefix (level conveys this) | `upstream unreachable` not `Error: upstream unreachable` |74| Specificity | State what failed, not generic failure | `upstream fetch failed` not `operation failed` |75| Brevity | Omit articles and filler words | `file too large` not `The file was too large` |76| Action | Use verb-noun or noun-verb pattern | `config loaded`, `invalid upstream url` |7778## Severity Levels7980| Level | When to use | Examples |81|-------|-------------|----------|82| ERROR | Unrecoverable failures requiring attention | `template parse failed`, `listen failed` |83| WARN | Degraded but recoverable situations | `upstream returned 5xx`, `cache eviction failed` |84| INFO | Normal business events | `request`, `server started`, `config loaded` |85| DEBUG | Internal details for troubleshooting | `cache hit`, `rewriting relative url`, `mdx import stripped` |8687## Structured Fields8889- Use snake_case for field names: `upstream_ms`, `content_type`, `cache_status`90- Suffix units: `_ms`, `_bytes`, `_count`91- Boolean fields: `has_mermaid`, `has_toc`92- Avoid embedding data in message string; use fields instead9394```go95// Bad96slog.Info(fmt.Sprintf("fetched %s in %dms", url, dur))9798// Good99slog.Info("upstream fetched", "upstream", url, "duration_ms", dur)100```101102---103> Converted and distributed by [TomeVault](https://tomevault.io/claim/air-gapped) — claim your Tome and manage your conversions.104<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io