jsonlog

Documentation

Overview

Package jsonlog provides a Logger that logs structured JSON to Stderr by default. When used on the various Cloud Compute environments (Cloud Run, Cloud Functions, GKE, etc.) these JSON messages will be parsed by the Cloud Logging agent and transformed into a message format that mirrors that of the Cloud Logging API.

Index

• type Logger
  • func NewLogger(parent string, opts ...LoggerOption) (*Logger, error)
  • func (l *Logger) Alertf(format string, a ...interface{})
  • func (l *Logger) Criticalf(format string, a ...interface{})
  • func (l *Logger) Debugf(format string, a ...interface{})
  • func (l *Logger) Emergencyf(format string, a ...interface{})
  • func (l *Logger) Errorf(format string, a ...interface{})
  • func (l *Logger) Infof(format string, a ...interface{})
  • func (l *Logger) Log(e logging.Entry)
  • func (l *Logger) Noticef(format string, a ...interface{})
  • func (l *Logger) Warnf(format string, a ...interface{})
  • func (l *Logger) WithLabels(labels map[string]string) *Logger
  • func (l *Logger) WithRequest(r *http.Request) *Logger
• type LoggerOption
  • func CommonLabels(m map[string]string) LoggerOption
  • func OnErrorHook(hook func(error)) LoggerOption
  • func WithWriter(w io.Writer) LoggerOption

Examples

• Logger.WithLabels
• NewLogger
• WithWriter (Multiwriter)

Types

type Logger

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

Logger is used for logging JSON entries.

func NewLogger

func NewLogger(parent string, opts ...LoggerOption) (*Logger, error)

NewLogger creates a Logger that logs structured JSON to Stderr. The value of parent must be in the format of:

projects/PROJECT_ID
folders/FOLDER_ID
billingAccounts/ACCOUNT_ID
organizations/ORG_ID

Example

package main

import (
	"cloud.google.com/go/logging/jsonlog"
)

func main() {
	l, err := jsonlog.NewLogger("projects/PROJECT_ID")
	if err != nil {
		// TODO: handle error.
	}
	l.Infof("Hello World!")
}

func (*Logger) Alertf

func (l *Logger) Alertf(format string, a ...interface{})

Alertf is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) Criticalf

func (l *Logger) Criticalf(format string, a ...interface{})

Criticalf is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) Debugf

func (l *Logger) Debugf(format string, a ...interface{})

Debugf is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) Emergencyf

func (l *Logger) Emergencyf(format string, a ...interface{})

Emergencyf is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) Errorf

func (l *Logger) Errorf(format string, a ...interface{})

Errorf is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) Infof

func (l *Logger) Infof(format string, a ...interface{})

Infof is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) Log

func (l *Logger) Log(e logging.Entry)

Log an Entry. Note that not all of the fields in entry will used when writting the log message, only those that are mentioned https://cloud.google.com/logging/docs/structured-logging will be logged.

func (*Logger) Noticef

func (l *Logger) Noticef(format string, a ...interface{})

Noticef is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) Warnf

func (l *Logger) Warnf(format string, a ...interface{})

Warnf is a convenience method for writing an Entry with a Debug Severity and the provided formatted message.

func (*Logger) WithLabels

func (l *Logger) WithLabels(labels map[string]string) *Logger

WithLabels creates a new JSONLogger based off an existing one. The labels provided will be added to the loggers existing labels, replacing any overlapping keys with the new values.

Example

package main

import (
	"cloud.google.com/go/logging/jsonlog"
)

func main() {
	l, err := jsonlog.NewLogger("projects/PROJECT_ID")
	if err != nil {
		// TODO: handle error.
	}
	l.Infof("Hello World!")

	// Create a logger that always provides additional context by adding labels
	// to all logged messages.
	l2 := l.WithLabels(map[string]string{"foo": "bar"})
	l2.Infof("Hello World, with more context!")
}

func (*Logger) WithRequest

func (l *Logger) WithRequest(r *http.Request) *Logger

WithRequest creates a new JSONLogger based off an existing one with request information populated. By giving a Logger a request context all logs will be auto-populated with some basic information about the request as well as tracing details, if included.

type LoggerOption

type LoggerOption interface {
	// contains filtered or unexported methods
}

LoggerOption is a configuration option for a Logger.

func CommonLabels

func CommonLabels(m map[string]string) LoggerOption

CommonLabels are labels that apply to all log entries written from a Logger, so that you don't have to repeat them in each log entry's Labels field. If any of the log entries contains a (key, value) with the same key that is in CommonLabels, then the entry's (key, value) overrides the one in CommonLabels.

func OnErrorHook

func OnErrorHook(hook func(error)) LoggerOption

OnErrorHook registers a function that will be called anytime an error occurs during logging.

func WithWriter

func WithWriter(w io.Writer) LoggerOption

WithWriter changes where the JSON payloads of a Logger are written to. By default they are written to Stderr.

Example (Multiwriter)

package main

import (
	"io"
	"os"

	"cloud.google.com/go/logging/jsonlog"
)

func main() {
	// Create a new writer that also logs messages to a second location
	w := io.MultiWriter(os.Stderr, os.Stdout)
	l, err := jsonlog.NewLogger("projects/PROJECT_ID", jsonlog.WithWriter(w))
	if err != nil {
		// TODO: handle error.
	}
	l.Infof("Hello World!")
}

Output:

{"message":"Hello World!","severity":"INFO"}