gslog

README

gslog

A Google Cloud Logging Handler implementation for slog.

Documentation

Overview

Package gslog contains a GCP logging implementation of slog.Handler.

Index

• Constants
• Variables
• func ExtractLabels(ctx context.Context) map[string]string
• func WithDefaultLogLevel(defaultLogLevel slog.Level) options.OptionProcessor
• func WithLabels(ctx context.Context, labels ...LabelPair) context.Context
• func WithLogLevel(logLevel slog.Level) options.OptionProcessor
• func WithLogLevelFromEnvVar() options.OptionProcessor
• func WithPodinfoLabels(root string) options.OptionProcessor
• func WithReplaceAttr(replaceAttr AttrMapper) options.OptionProcessor
• func WithSourceAdded() options.OptionProcessor
• type AttrMapper
• type AugmentEntryFn
• type GcpHandler
  • func NewGcpHandler(logger *logging.Logger, opts ...options.OptionProcessor) (*GcpHandler, error)
  • func NewGcpLoggerWithOptions(logger logger, opts ...options.OptionProcessor) *GcpHandler
  • func (h *GcpHandler) Enabled(_ context.Context, level slog.Level) bool
  • func (h *GcpHandler) Handle(ctx context.Context, record slog.Record) error
  • func (h *GcpHandler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *GcpHandler) WithGroup(name string) slog.Handler
  • func (h *GcpHandler) WithLeveler(leveler slog.Leveler) *GcpHandler
• type LabelPair
  • func Label(key, value string) LabelPair
• type Options

Constants

const (
	// LevelNotice means normal but significant events, such as start up,
	// shut down, or configuration.
	LevelNotice = slog.Level(2)
	// LevelCritical means events that cause more severe problems or brief
	// outages.
	LevelCritical = slog.Level(12)
	// LevelAlert means a person must take an action immediately.
	LevelAlert = slog.Level(16)
	// LevelEmergency means one or more systems are unusable.
	LevelEmergency = slog.Level(20)
)

const (
	K8sPodPrefix = "k8s-pod/"
)

const (
	LevelUnknown slog.Level = math.MaxInt
)

Variables

var Discard logger = discard{}

var (
	ErrNoLogLevelSet = fmt.Errorf("no level set for logging")
)

Functions

func ExtractLabels

func ExtractLabels(ctx context.Context) map[string]string

ExtractLabels extracts labels from the ctx. These labels were associated with the context using WithLabels.

func WithDefaultLogLevel

func WithDefaultLogLevel(defaultLogLevel slog.Level) options.OptionProcessor

WithDefaultLogLevel returns an option that specifies the default log level for logging.

func WithLabels

func WithLabels(ctx context.Context, labels ...LabelPair) context.Context

WithLabels returns a new Context with labels to be used in the GCP log entries produced using that context.

func WithLogLevel

func WithLogLevel(logLevel slog.Level) options.OptionProcessor

WithLogLevel returns an option that specifies the log level for logging. Explicitly setting the log level here takes precedence over the other options.

func WithLogLevelFromEnvVar

func WithLogLevelFromEnvVar() options.OptionProcessor

WithLogLevelFromEnvVar returns an option that specifies the log level for logging comes from tne environmental variable GSLOG_LOG_LEVEL.

func WithPodinfoLabels

func WithPodinfoLabels(root string) options.OptionProcessor

WithPodinfoLabels returns a Option that directs that the slog.Handler to include labels from the Kubernetes Downward API podinfo labels file. The labels file is expected to be found in the directory specified by root and MUST be named "labels", per the Kubernetes Downward API for Pods.

The labels are prefixed with "k8s-pod/" to adhere to the Google Cloud Logging conventions for Kubernetes Pod labels.

func WithReplaceAttr

func WithReplaceAttr(replaceAttr AttrMapper) options.OptionProcessor

WithReplaceAttr returns an option that specifies an attribute mapper used to rewrite each non-group attribute before it is logged.

func WithSourceAdded

func WithSourceAdded() options.OptionProcessor

WithSourceAdded returns an option that causes the handler to compute the source code position of the log statement and add a slog.SourceKey attribute to the output.

Types

type AttrMapper

type AttrMapper func(groups []string, a slog.Attr) slog.Attr

AttrMapper is called to rewrite each non-group attribute before it is logged. The attribute's value has been resolved (see [Value.Resolve]). If replaceAttr returns a zero Attr, the attribute is discarded.

The built-in attributes with keys "time", "level", "source", and "msg" are passed to this function, except that time is omitted if zero, and source is omitted if addSource is false.

The first argument is a list of currently open groups that contain the Attr. It must not be retained or modified. replaceAttr is never called for Group attributes, only their contents. For example, the attribute list

Int("a", 1), Group("g", Int("b", 2)), Int("c", 3)

results in consecutive calls to replaceAttr with the following arguments:

nil, Int("a", 1)
[]string{"g"}, Int("b", 2)
nil, Int("c", 3)

AttrMapper can be used to change the default keys of the built-in attributes, convert types (for example, to replace a `time.Time` with the integer seconds since the Unix epoch), sanitize personal information, or remove attributes from the output.

type AugmentEntryFn

type AugmentEntryFn func(ctx context.Context, e *logging.Entry)

type GcpHandler

type GcpHandler struct {
	// contains filtered or unexported fields
}

GcpHandler is a Google Cloud Logging backed slog handler.

func NewGcpHandler

func NewGcpHandler(logger *logging.Logger, opts ...options.OptionProcessor) (*GcpHandler, error)

NewGcpHandler creates a Google Cloud Logging backed log.Logger.

func NewGcpLoggerWithOptions

func NewGcpLoggerWithOptions(logger logger, opts ...options.OptionProcessor) *GcpHandler

func (*GcpHandler) Enabled

func (h *GcpHandler) Enabled(_ context.Context, level slog.Level) bool

func (*GcpHandler) Handle

func (h *GcpHandler) Handle(ctx context.Context, record slog.Record) error

Handle will handle a slog.Record, as described in the interface's documentation. It will translate the slog.Record into a logging.Entry that's filled with a *structpb.Value as a Entry Payload.

func (*GcpHandler) WithAttrs

func (h *GcpHandler) WithAttrs(attrs []slog.Attr) slog.Handler

func (*GcpHandler) WithGroup

func (h *GcpHandler) WithGroup(name string) slog.Handler

func (*GcpHandler) WithLeveler

func (h *GcpHandler) WithLeveler(leveler slog.Leveler) *GcpHandler

WithLeveler returns a copy of the handler, provisioned with the supplied leveler.

type LabelPair

type LabelPair struct {
	// contains filtered or unexported fields
}

LabelPair represents a key-value string pair.

func Label

func Label(key, value string) LabelPair

Label returns a new LabelPair from a key and a value.

type Options

type Options struct {
	options.Options
}

Options holds information needed to construct an instance of GcpHandler.