gcp

Documentation

Overview

Package gcp provides a handler for emitting log records to GCP Cloud Logging.

The handler formats records to match GCP Cloud Logging JSON schema. It also integrates logs with GCP Cloud Trace and GCP Error Reporting if enabled.

Index

• Constants
• func New(opts ...Option) slog.Handler
• type Option
  • func WithCallers(callers func(error) []uintptr) Option
  • func WithErrorReporting(service, version string) Option
  • func WithLevel(level slog.Leveler) Option
  • func WithTrace(project string) Option
  • func WithTraceContext(...) Option
  • func WithWriter(writer io.Writer) Option

Constants

const (
	// TraceKey is the key used by the [ID of the whole trace] forest and is used to uniquely
	// identify a distributed trace through a system. It is represented as a 16-byte array,
	// for example, 4bf92f3577b34da6a3ce929d0e0e4736.
	// All bytes as zero (00000000000000000000000000000000) is considered an invalid value.
	//
	// [ID of the whole trace]: https://www.w3.org/TR/trace-context/#trace-id
	TraceKey = "trace_id"
	// SpanKey is the key used by the [ID of this request] as known by the caller.
	// It is represented as an 8-byte array, for example, 00f067aa0ba902b7.
	// All bytes as zero (0000000000000000) is considered an invalid value.
	//
	// [ID of this request]: https://www.w3.org/TR/trace-context/#parent-id
	SpanKey = "span_id"
	// TraceFlagsKey is the key used by an 8-bit field that controls [tracing flags]
	// such as sampling, trace level, etc.
	//
	// [tracing flags]: https://www.w3.org/TR/trace-context/#trace-flags
	TraceFlagsKey = "trace_flags"
)

Keys for W3C Trace Context attributes by following Trace Context in non-OTLP Log Formats.

Functions

func New

func New(opts ...Option) slog.Handler

New creates a new Handler with the given Option(s). The handler formats records to match GCP Cloud Logging JSON schema.

Types

type Option

type Option func(*options)

Option configures the Handler with specific options.

func WithCallers

func WithCallers(callers func(error) []uintptr) Option

WithCallers provides a function to get callers on the calling goroutine's stack while WithErrorReporting has been called. If the callers returns empty slice, the handler gets stack trace from debug.Stack.

If Callers is nil, the handler checks method `Callers() []uintptr` on the error.

func WithErrorReporting

func WithErrorReporting(service, version string) Option

WithErrorReporting enables logs reported as error events to GCP Error Reporting.

func WithLevel

func WithLevel(level slog.Leveler) Option

WithLevel provides the minimum record level that will be logged. The handler discards records with lower levels.

If Level is nil, the handler assumes LevelInfo.

func WithTrace

func WithTrace(project string) Option

WithTrace enables trace information added to the log for GCP Cloud Trace integration. The handler use function set in WithTraceContext to get trace information if it does not present in record's attributes yet.

func WithTraceContext

func WithTraceContext(provider func(context.Context) (traceID [16]byte, spanID [8]byte, traceFlags byte)) Option

WithTraceContext providers the W3C Trace Context while WithTrace has been called.

If it is nil, the handler finds trace information from record's attributes.

func WithWriter

func WithWriter(writer io.Writer) Option

WithWriter provides the writer to which the handler writes.

If Writer is nil, the handler assumes os.Stderr.