Documentation
¶
Overview ¶
Package observability provides cross-cutting structured logging used by huan's release/deploy pipelines. The Logger emits JSON lines per CLAUDE.md's Full-Lifecycle Observability mandate.
Logger was previously in internal/deploy/logging.go; it was extracted into its own package once release became the second consumer. The abstraction is domain-agnostic (no deploy/release specifics); Report-shaped types stay in their domain packages because their fields differ.
Index ¶
- func NewTraceID() string
- type EventType
- type Logger
- func (l *Logger) Log(spanID string, event EventType, payload map[string]any)
- func (l *Logger) LogError(spanID string, err error, payload map[string]any)
- func (l *Logger) LogFunctionEnd(spanID string, duration time.Duration, payload map[string]any)
- func (l *Logger) LogFunctionStart(spanID string, payload map[string]any) string
- func (l *Logger) TraceID() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewTraceID ¶
func NewTraceID() string
NewTraceID generates a random 16-byte hex-encoded id (32 chars). Exported so callers can pre-generate a trace id and use it both in early-return Report values and in the Logger.
Types ¶
type EventType ¶
type EventType string
EventType enumerates the structured log event types mandated by CLAUDE.md (Full-Lifecycle Observability).
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger emits JSON-structured log lines to stderr (default). Each line has:
{
"timestamp": "2026-06-13T...",
"trace_id": "<invocation id>",
"span_id": "<step id within this invocation>",
"event_type": "Function_Start|Function_End|Branch|Error|Point",
"payload": { ... arbitrary fields ... }
}
The Logger keeps no state about active spans — callers pass an explicit spanID per call. This avoids the implicit-global-state footguns common in context-based loggers and makes the log calls grep-friendly.
Logger is safe for concurrent use.
func NewLogger ¶
NewLogger returns a Logger that writes to stderr. traceID is propagated to every log line for correlation; if empty, a random one is generated.
func NewLoggerWithWriter ¶
NewLoggerWithWriter is like NewLogger but lets tests inject a buffer. traceID is auto-generated when empty, matching NewLogger's contract.
func (*Logger) LogFunctionEnd ¶
func (*Logger) LogFunctionStart ¶
LogFunctionStart and LogFunctionEnd record the boundary of a logical step (e.g. an HTTP API call or a sub-command phase). They return the same spanID for chaining.
start := l.LogFunctionStart("upload-file", map[string]any{"path": p})
defer l.LogFunctionEnd(start, time.Since(...), nil)
Source Files