logging

Documentation

Overview

Package logging contains a Google Cloud Logging client.

This package is experimental and subject to API changes.

Index

• Constants
• Variables
• type Client
  • func NewClient(ctx context.Context, projectID, logName string, opts ...cloud.ClientOption) (*Client, error)
  • func (c *Client) Flush() error
  • func (c *Client) Log(e Entry) error
  • func (c *Client) LogSync(e Entry) error
  • func (c *Client) Logger(v Level) *log.Logger
  • func (c *Client) Ping() error
  • func (c *Client) Writer(v Level) io.Writer
• type Entry
• type Level
  • func (v Level) String() string

Constants

const Scope = api.LoggingWriteScope

Scope is the OAuth2 scope necessary to use Google Cloud Logging.

Variables

var ErrOverflow = errors.New("logging: log entry overflowed buffer limits")

Types

type Client

type Client struct {

	// ServiceName may be "appengine.googleapis.com",
	// "compute.googleapis.com" or "custom.googleapis.com".
	//
	// The default is "custom.googleapis.com".
	//
	// The service name is only used by the API server to
	// determine which of the labels are used to index the logs.
	ServiceName string

	// CommonLabels are metadata labels that apply to all log
	// entries in this request, so that you don't have to repeat
	// them in each log entry's metadata.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.
	CommonLabels map[string]string

	// BufferLimit is the maximum number of items to keep in memory
	// before flushing. Zero means automatic. A value of 1 means to
	// flush after each log entry.
	// The default is currently 10,000.
	BufferLimit int

	// FlushAfter optionally specifies a threshold count at which buffered
	// log entries are flushed, even if the BufferInterval has not yet
	// been reached.
	// The default is currently 10.
	FlushAfter int

	// BufferInterval is the maximum amount of time that an item
	// should remain buffered in memory before being flushed to
	// the logging service.
	// The default is currently 1 second.
	BufferInterval time.Duration

	// Overflow is a function which runs when the Log function
	// overflows its configured buffer limit. If nil, the log
	// entry is dropped. The return value from Overflow is
	// returned by Log.
	Overflow func(*Client, Entry) error
	// contains filtered or unexported fields
}

Client is a Google Cloud Logging client. It must be constructed via NewClient.

func NewClient

func NewClient(ctx context.Context, projectID, logName string, opts ...cloud.ClientOption) (*Client, error)

NewClient returns a new log client, logging to the named log in the provided project.

The exported fields on the returned client may be modified before the client is used for logging. Once log entries are in flight, the fields must not be modified.

func (*Client) Flush

func (c *Client) Flush() error

Flush flushes any buffered log entries.

func (*Client) Log

func (c *Client) Log(e Entry) error

Log queues an entry to be sent to the logging service, subject to the Client's parameters. By default, the log will be flushed within one second. Log only returns an error if the entry is invalid or the queue is at capacity. If the queue is at capacity and the entry can't be added, Log returns either ErrOverflow when c.Overflow is nil, or the value returned by c.Overflow.

func (*Client) LogSync

func (c *Client) LogSync(e Entry) error

LogSync logs e synchronously without any buffering. This is mostly intended for debugging or critical errors.

func (*Client) Logger

func (c *Client) Logger(v Level) *log.Logger

Logger returns a *log.Logger for the provided log level.

A Logger for each Level is pre-allocated by NewClient with an empty prefix and no flags. This Logger accessor does not allocate. Callers wishing to use alternate flags (such as log.Lshortfile) may mutate the returned Logger with SetFlags. Such mutations affect all callers in the program.

func (*Client) Ping

func (c *Client) Ping() error

Ping reports whether the client's connection to Google Cloud Logging and the authentication configuration are valid. To accomplish this, Ping writes a log entry "ping" to a log named "ping".

func (*Client) Writer

func (c *Client) Writer(v Level) io.Writer

Writer returns an io.Writer for the provided log level.

Each Write call on the returned Writer generates a log entry.

This Writer accessor does not allocate, so callers do not need to cache.

type Entry

type Entry struct {
	// Time is the time of the entry. If the zero value, the current time is used.
	Time time.Time

	// Level is log entry's severity level.
	// The zero value means no assigned severity level.
	Level Level

	// Payload must be either a string, []byte, or something that
	// marshals via the encoding/json package to a JSON object
	// (and not any other type of JSON value).
	Payload interface{}

	// Labels optionally specifies key/value labels for the log entry.
	// Depending on the Client's ServiceName, these are indexed differently
	// by the Cloud Logging Service.
	// See https://cloud.google.com/logging/docs/logs_index
	// The Client.Log method takes ownership of this map.
	Labels map[string]string
}

Entry is a log entry.

type Level

type Level int

Level is the log level.

const (
	// Default means no assigned severity level.
	Default Level = iota
	Debug
	Info
	Warning
	Error
	Critical
	Alert
	Emergency
)

func (Level) String

func (v Level) String() string