/golang-logging

name: golang-logging
description: Standards for structured logging and observability in Golang. Use when adding structured logging or tracing to Go services.
metadata:
  triggers:
    files:
    - 'go.mod'
    - 'pkg/logger/**'
    keywords:
    - logging
    - slog
    - structured logging
    - zap

Golang Logging Standards

**Priority: P1 (HIGH)**

Principles

• **Structured Logging**: Use JSON or structured key-value attributes. Machine-readable and filterable.
• **Strict Single-Log Boundary**: Log errors once where they are handled or translated at the boundary (service or handler level). **Never double-log** in repository, utility, or deep helper functions—wrap and return errors instead.
• **Typed Context Keys**: Always use private typed keys (`type ctxKey string`) for storing and retrieving request-scoped logger attributes.
• **Business Traceability vs PII Redaction**: Include non-sensitive business identifiers (e.g. tenant ID, organization code, order number) for traceability. Strictly redact credentials, API tokens, passwords, and sensitive PII.
• **Leveled Logging**: Debug, Info, Warn, Error.
• **No `log.Fatal`**: Avoid terminating apps inside libraries. Return errors instead; only `main()` should handle process exit.

Libraries

• **`log/slog` (Recommended Stdlib)**: Stdlib since Go 1.21. Fast, structured, zero-dep.
• **Zap (`uber-go/zap`)**: Production-grade structured logger for high-throughput microservices.
• **Zerolog**: Zero allocation, fast JSON logger.

Workflow: Set Up Structured Logging

1. Initialize structured logger at startup in `main()` with standard JSON output. 2. Inject request correlation IDs (TraceID, RequestID) via middleware using typed context keys. 3. Pass logger via context (`logger.FromContext(ctx)`) or constructor injection. 4. Log at the application boundary on error; wrap errors upstream without intermediate logging.

See [slog setup and usage examples](references/slog-patterns.md)

Anti-Patterns

• **No Double-Logging**: Do not log an error in the repository/database helper AND log it again in the service/handler.
• **No fmt.Println in production**: Use structured, leveled loggers.
• **No Untyped Context Keys**: Avoid `context.WithValue(ctx, "logger", l)` with raw string keys.
• **No Secrets in Logs**: Redact bearer tokens, passwords, and sensitive personal info.
• **No log.Fatal in libraries**: Return errors; only `main()` should call `os.Exit`.

References

• [Slog Patterns](references/slog-patterns.md)