Documentation
¶
Overview ¶
Package log provides sane default loggers using slog.
Index ¶
- Variables
- func JSONHandler(w io.Writer, opts *slog.HandlerOptions) slog.Handler
- func NewDefaultEnvLogger(opts ...Opt) *slog.Logger
- func ParseLogLevel(level string) slog.Level
- func ParseLogLevelFromEnv() slog.Level
- func ParseSource(source string) bool
- func ParseSourceFromEnv() bool
- func TextHandler(w io.Writer, opts *slog.HandlerOptions) slog.Handler
- type HandlerFn
- type Opt
- func WithGCP(projectID string) Opt
- func WithGCPReplacer(short bool) Opt
- func WithGCPTraceContext(projectID string) Opt
- func WithHandlerFn(h HandlerFn) Opt
- func WithLeveler(l slog.Leveler) Opt
- func WithOutput(w io.Writer) Opt
- func WithReplacer(fn func([]string, slog.Attr) slog.Attr) Opt
- func WithShortSource(short bool) Opt
- func WithSource(enabled bool) Opt
- func WithTraceContext(tc TraceContext) Opt
- type TraceContext
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( TraceID = "trace_id" SpanID = "span_id" TraceSampled = "trace_sampled" )
Functions ¶
func JSONHandler ¶
JSONHandler is a LogHandlerFn shim for slog.NewJSONHandler.
func NewDefaultEnvLogger ¶
NewDefaultEnvLogger creates new slog.Logger using sane default configuration and sets it as a default logger. Environment variables can be used to configure loggers format and level. Options can be provided to overwrite defaults.
Name: Value: LOG_LEVEL DEBUG|INFO|WARN|ERROR LOG_FORMAT JSON|TEXT
Note: LOG_FORMAT can't be changed at runtime.
Example ¶
package main
import (
"log/slog"
"github.com/elisasre/go-common/v2/log"
)
func main() {
log.NewDefaultEnvLogger()
slog.Info("Hello world")
slog.Error("Some error")
}
Output:
func ParseLogLevel ¶
ParseLogLevel turns string into slog.Level using case-insensitive parser. If the input doesn't match to any slog.Level then slog.LevelInfo is used.
func ParseLogLevelFromEnv ¶
ParseLogLevelFromEnv turns LOG_LEVEL env variable into slog.Level using logic from ParseLogLevel.
func ParseSource ¶
func ParseSourceFromEnv ¶
func ParseSourceFromEnv() bool
func TextHandler ¶
TextHandler is a LogHandlerFn shim for slog.NewTextHandler.
Types ¶
type HandlerFn ¶
HandlerFn is a shim type for slog's NewHandler functions.
func ParseFormat ¶
ParseFormat parses string into supported log handler function. If the input doesn't match to any supported format then JSON is used.
func ParseFormatFromEnv ¶
func ParseFormatFromEnv() HandlerFn
ParseFormatFromEnv turns LOG_FORMAT env variable into slog.Handler function using ParseFormat.
type Opt ¶
type Opt func(*builder)
func WithGCP ¶ added in v2.8.0
WithGCP configures the logger for Google Cloud Logging. It applies both WithGCPReplacer (with short source paths) and WithGCPTraceContext to produce structured logs compatible with GCP Cloud Logging and Cloud Trace.
The projectID must be the GCP project where Cloud Trace stores spans. In multi-project setups where traces are exported to a central observability project, use that project's ID — not the project where the workload runs.
See https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
func WithGCPReplacer ¶ added in v2.1.9
WithGCPReplacer sets slog.HandlerOptions.ReplaceAttr to GCP structured logging format. It remaps standard slog attribute keys to GCP-specific names:
- source -> logging.googleapis.com/sourceLocation (with line as string)
- level -> severity (with GCP severity names)
- time -> timestamp
- msg -> message
https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
func WithGCPTraceContext ¶ added in v2.8.0
WithGCPTraceContext configures trace context attributes for Google Cloud Logging. It sets the attribute keys to the GCP-specific names and formats the trace ID as "projects/{projectID}/traces/{traceID}" which enables linking between Cloud Logging and Cloud Trace in the GCP console.
The projectID must be the GCP project where Cloud Trace stores spans. In multi-project setups where traces are exported to a central observability project, use that project's ID — not the project where the workload runs.
GCP special fields:
- logging.googleapis.com/trace
- logging.googleapis.com/spanId
- logging.googleapis.com/trace_sampled
See https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
func WithHandlerFn ¶
WithHandlerFn can be used to provide slog.Handler lazily.
func WithReplacer ¶
WithReplacer sets slog.HandlerOptions.ReplaceAttr. This resets any previously configured replacer functions (from WithShortSource, WithGCPReplacer, etc.) and sets the given function as the sole replacer. Use this as an escape hatch for full control.
func WithShortSource ¶
WithShortSource sets slog.ReplaceAttr source file as short format.
func WithTraceContext ¶ added in v2.8.0
func WithTraceContext(tc TraceContext) Opt
WithTraceContext sets custom trace context configuration for the span context log handler. This allows customizing the attribute keys and value formatters for trace ID, span ID, and trace sampled fields.
type TraceContext ¶ added in v2.8.0
type TraceContext struct {
// TraceIDKey is the attribute key for the trace ID (default: "trace_id").
TraceIDKey string
// SpanIDKey is the attribute key for the span ID (default: "span_id").
SpanIDKey string
// TraceSampledKey is the attribute key for the trace sampled flag (default: "trace_sampled").
TraceSampledKey string
// TraceIDFormatter formats the trace ID string. If nil, the raw hex trace ID is used.
TraceIDFormatter func(trace.TraceID) string
// SpanIDFormatter formats the span ID string. If nil, the raw hex span ID is used.
SpanIDFormatter func(trace.SpanID) string
}
TraceContext configures how OpenTelemetry span context attributes are added to log records.
Source Files