logging-config

name	logging-config
description	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.
metadata	{"author":"air-gapped"}

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.