home / skills / hoangnguyen0403 / agent-skills-standard / logging

logging skill

This skill enforces structured, contextual Golang logging with leveled outputs and safe library usage to improve observability.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill logging

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---
name: Logging
description: Standards for structured logging and observability in Golang.
metadata:
  labels: [golang, logging, slog, zap, observability]
  triggers:
    files: ['go.mod', 'pkg/logger/**']
    keywords: [logging, slog, structured logging, zap]
---

# Golang Logging Standards

## **Priority: P1 (STANDARD)**

## Principles

- **Structured Logging**: Use JSON or structured text. Readable by machines and humans.
- **Leveled Logging**: Debug, Info, Warn, Error.
- **Contextual**: Include correlation IDs (TraceID, RequestID) in logs.
- **No `log.Fatal`**: Avoid terminating app inside libraries. Return error instead. Only `main` should exit.

## Libraries

- **`log/slog` (Recommended)**: Stdlib since Go 1.21. Fast, structured, zero-dep.
- **Zap (`uber-go/zap`)**: High performance, good if pre-1.21 or extreme throughput needed.
- **Zerolog**: Zero allocation, fast JSON logger.

## Guidelines

- Initialize logger at startup.
- Inject logger or use a global singleton configured at startup (pragmatic choice).
- Use `slog.Attr` for structured data.

## References

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

Overview

This skill documents standards for structured logging and observability in Go applications. It focuses on consistent, machine-readable logs, leveled logging, and contextual fields like trace and request IDs to improve debuggability and tracing across services. The guidance favors Go 1.21's slog but covers high-performance alternatives for special cases.

How this skill works

The skill describes what to capture in logs, which libraries to prefer, and how to initialize and propagate loggers across an application. It prescribes structured JSON logs, common levels (Debug, Info, Warn, Error), and inclusion of contextual fields such as TraceID or RequestID on every relevant entry. It also explains lifecycle rules: configure logger at startup, inject or provide a singleton, and avoid terminating the app from libraries.

When to use it

New or existing Go services that require consistent observability and traceability
Microservices where logs must be correlated with traces and metrics
High-throughput applications that need low-overhead JSON logging
Libraries and shared packages that must avoid killing the process
Upgrading to Go 1.21 or evaluating logging libraries for performance

Best practices

Prefer structured logging (JSON or keyed attributes) so logs are machine and human readable
Use leveled logging: Debug, Info, Warn, Error — avoid ad-hoc levels
Include contextual IDs (TraceID, RequestID, user/session identifiers) on relevant log entries
Initialize logger once at startup and inject a logger instance or use a configured global singleton as a pragmatic choice
Avoid log.Fatal or terminating calls inside libraries; return errors and let main decide process lifecycle
Choose slog (stdlib) for zero-dependency structured logs; use zap or zerolog only when you need extreme throughput or are on pre-1.21 Go

Example use cases

HTTP API: attach RequestID and TraceID from middleware and log each request lifecycle with structured fields
Background worker: initialize a logger with service and environment fields, include job IDs for correlation
Library package: accept a logger interface or return errors rather than calling os.Exit or log.Fatal
High-performance ingest service: use zap or zerolog for minimal allocation JSON logs and high throughput
Migration plan: switch to slog in a controlled rollout, keep compatibility layers for existing log consumers

FAQ

Should I always use slog in Go?

Prefer slog for most projects because it is in the standard library (Go 1.21+) and provides structured, zero-dependency logging. Use zap or zerolog only if you need extreme performance or are on an older Go version.

How do I attach TraceID to logs?

Extract TraceID from request context (or tracing library) in middleware, then include it as a structured attribute on every log entry so logs can be correlated with traces and metrics.