logging

Documentation

Overview

Package logging은 runtime 서비스용 공용 구조화 로깅 helper를 제공합니다.

패키지 개요

이 패키지는 slog 기반 구조화 로깅을 공통화합니다. 호출부는 event, message, slog.Attr를 전달하고, 패키지는 context에 전파된 request_id, job_id, runtime, component 값을 자동으로 병합합니다.

operation lifecycle 로깅, 민감값 마스킹 handler, 파일 로깅과 압축 archive, OpenTelemetry trace/span 상관관계 주입도 이 패키지의 책임입니다. 서비스별 로거 생성과 운영 로그 규칙은 이 패키지의 공개 진입점을 통해 맞춥니다.

주요 사용 패턴

ctx = logging.WithJobID(ctx, "ingest-job")
ctx = logging.WithComponent(ctx, "poller")
err := logging.RunOperation(ctx, logger, logging.OperationOptions{
    Name: "ingest.batch",
}, func(ctx context.Context) error {
    return process(ctx)
})

logging.Info(ctx, logger, "youtube.poll.started", "poll started",
    logging.Runtime("youtube-producer"),
)

Index

• func ContextAttrs(ctx context.Context) []slog.Attr
• func Debug(ctx context.Context, logger *slog.Logger, event, message string, ...)
• func DurationMS(d time.Duration) slog.Attr
• func EnableFileLogging(config Config, fileName string) (*slog.Logger, error)
• func EnableFileLoggingWithLevel(config Config, fileName, level string) (*slog.Logger, error)
• func EnableFileLoggingWithOTel(config Config, fileName string, enableOTel bool) (*slog.Logger, error)
• func EnableFileLoggingWithOptions(config Config, fileName string, opts Options) (*slog.Logger, io.Closer, error)
• func Error(ctx context.Context, logger *slog.Logger, event, message string, ...)
• func ErrorAttrs(err error) []slog.Attr
• func Event(event string) slog.Attr
• func Info(ctx context.Context, logger *slog.Logger, event, message string, ...)
• func Log(ctx context.Context, logger *slog.Logger, level slog.Level, ...)
• func LogAndWrapError(ctx context.Context, logger *slog.Logger, op string, err error, ...) error
• func LogWarnWithErrorAttrs(ctx context.Context, logger *slog.Logger, event, message string, err error, ...)
• func NewLogger() *slog.Logger
• func NewTestLogger() *slog.Logger
• func NewTestLoggerWithOutput(w io.Writer) *slog.Logger
• func Operation(name string) slog.Attr
• func RequestID(id string) slog.Attr
• func RunOperation(ctx context.Context, logger *slog.Logger, opts OperationOptions, ...) error
• func Runtime(runtime string) slog.Attr
• func SinceMS(start time.Time) slog.Attr
• func Warn(ctx context.Context, logger *slog.Logger, event, message string, ...)
• func WithComponent(ctx context.Context, component string) context.Context
• func WithJobID(ctx context.Context, jobID string) context.Context
• func WithRequestID(ctx context.Context, requestID string) context.Context
• func WithRuntime(ctx context.Context, runtime string) context.Context
• type Config
• type OperationOptions
• type Options

Functions

func ContextAttrs

func ContextAttrs(ctx context.Context) []slog.Attr

func Debug

func Debug(ctx context.Context, logger *slog.Logger, event, message string, attrs ...slog.Attr)

func DurationMS

func DurationMS(d time.Duration) slog.Attr

func EnableFileLogging

func EnableFileLogging(config Config, fileName string) (*slog.Logger, error)

func EnableFileLoggingWithLevel

func EnableFileLoggingWithLevel(config Config, fileName, level string) (*slog.Logger, error)

func EnableFileLoggingWithOTel

func EnableFileLoggingWithOTel(config Config, fileName string, enableOTel bool) (*slog.Logger, error)

func EnableFileLoggingWithOptions

func EnableFileLoggingWithOptions(config Config, fileName string, opts Options) (*slog.Logger, io.Closer, error)

EnableFileLoggingWithOptions는 io.Closer를 함께 반환한다. Closer는 비동기 stdout lane의 잔여 드레인과 lumberjack 파일 핸들 정리를 담당하며, 콘솔 전용 구성에서는 nil이다.

func Error

func Error(ctx context.Context, logger *slog.Logger, event, message string, attrs ...slog.Attr)

func ErrorAttrs

func ErrorAttrs(err error) []slog.Attr

func Event

func Event(event string) slog.Attr

func Info

func Info(ctx context.Context, logger *slog.Logger, event, message string, attrs ...slog.Attr)

func Log

func Log(ctx context.Context, logger *slog.Logger, level slog.Level, event, message string, attrs ...slog.Attr)

func LogAndWrapError

func LogAndWrapError(ctx context.Context, logger *slog.Logger, op string, err error, attrs ...slog.Attr) error

LogAndWrapError는 에러를 구조화 로그로 남긴 뒤 op prefix로 감싸 반환합니다.

func LogWarnWithErrorAttrs

func LogWarnWithErrorAttrs(ctx context.Context, logger *slog.Logger, event, message string, err error, attrs ...slog.Attr)

LogWarnWithErrorAttrs는 반환하지 않는 background failure를 WARN 로그와 표준 error attr로 남깁니다.

func NewLogger

func NewLogger() *slog.Logger

func NewTestLogger

func NewTestLogger() *slog.Logger

func NewTestLoggerWithOutput

func NewTestLoggerWithOutput(w io.Writer) *slog.Logger

func Operation

func Operation(name string) slog.Attr

func RequestID

func RequestID(id string) slog.Attr

func RunOperation

func RunOperation(ctx context.Context, logger *slog.Logger, opts OperationOptions, fn func(context.Context) error) error

func Runtime

func Runtime(runtime string) slog.Attr

func SinceMS

func SinceMS(start time.Time) slog.Attr

func Warn

func Warn(ctx context.Context, logger *slog.Logger, event, message string, attrs ...slog.Attr)

func WithComponent

func WithComponent(ctx context.Context, component string) context.Context

func WithJobID

func WithJobID(ctx context.Context, jobID string) context.Context

func WithRequestID

func WithRequestID(ctx context.Context, requestID string) context.Context

func WithRuntime

func WithRuntime(ctx context.Context, runtime string) context.Context

Types

type Config

type Config struct {
	Level      string
	Dir        string
	MaxSizeMB  int
	MaxBackups int
	MaxAgeDays int
	Compress   bool
}

type OperationOptions

type OperationOptions struct {
	Name         string
	IDPrefix     string
	Runtime      string
	Component    string
	StartEvent   string
	SuccessEvent string
	FailureEvent string
	SkipStartLog bool
	// Level은 started/succeeded 로그 레벨이다. failed는 항상 Error로 기록한다.
	Level slog.Level
	Attrs []slog.Attr
}

type Options

type Options struct {
	// AsyncStdout이 true면 stdout 사본 lane을 drop-on-full 비동기 writer로 감싸
	// stdout fd 정체가 로깅 전체를 블로킹하지 않게 한다. 파일 lane은 동기 기록을 유지한다.
	// 파일 lane이 없는 콘솔 전용 구성(Dir 빈 값)에서는 유일한 기록처를 잃을 수 있어 적용하지 않는다.
	AsyncStdout bool
	// OTel이 true면 span context의 trace_id/span_id를 로그 attr로 상관시킨다.
	OTel bool
}

Options는 파일 로깅의 선택 동작을 제어한다.