grouplogger

README

grouplogger

Grouplogger is a specialized Stackdriver logging client for writing groups of log entries. Group entries by contexts that make sense for your application––e.g. by Stackdriver Trace, HTTP request, or Pub/Sub message.

(Stackdriver documentation: Viewing related request log entries)

u, _ := url.Parse("https://api.vimeo.com/")

// Stackdriver requires a non-nil http.Request.
req := &http.Request{
  // Including a trace ID is optional.
  Header: http.Header{
    "X-Cloud-Trace-Context": []string{"your-trace-id"},
  },
  // Stackdriver requires the http.Request to have a URL.
  URL: u,
}

ctx := context.Background()
cli, _ := grouplogger.NewClient(ctx, "your-project-id")

logger := cli.Logger(req, "logname")

logger.Info("Entry with Info severity.")
logger.Notice(map[string][]string{
  "Words": []string{"structured", "data", "in", "entries"},
})
logger.Warning("Look out! Entry with Warning severity.")

logger.Close()

_ = cli.Close()

Documentation

Overview

Package grouplogger wraps a Stackdriver logging client to facilitate writing groups of log entries, similar to the default behavior in Google App Engine Standard.

var r *http.Request

ctx := context.Background()
cli, err := NewClient(ctx, "logging-parent")
if err != nil {
	// Handle "failed to generate Stackdriver client."
}

logger := cli.Logger(r, "app_identifier", logging.CommonLabels(WithHostname(nil)))

logger.Info("Info log entry body.")
logger.Error("Error log entry body.")

logger.Close()

Index

• func WithHostname(labels map[string]string) map[string]string
• type Client
  • func NewClient(ctx context.Context, parent string, opts ...option.ClientOption) (*Client, error)
  • func (client *Client) Close() error
  • func (client *Client) Logger(r *http.Request, name string, opts ...logging.LoggerOption) *GroupLogger
  • func (client *Client) Ping(ctx context.Context) error
  • func (client *Client) SetOnError(f func(err error))
• type GroupLogger
  • func (gl *GroupLogger) Alert(payload interface{})
  • func (gl *GroupLogger) Close()
  • func (gl *GroupLogger) CloseWith(stats *logging.HTTPRequest)
  • func (gl *GroupLogger) Critical(payload interface{})
  • func (gl *GroupLogger) Debug(payload interface{})
  • func (gl *GroupLogger) Default(payload interface{})
  • func (gl *GroupLogger) Emergency(payload interface{})
  • func (gl *GroupLogger) Error(payload interface{})
  • func (gl *GroupLogger) Info(payload interface{})
  • func (gl *GroupLogger) Log(e logging.Entry)
  • func (gl *GroupLogger) LogInnerEntry(entry logging.Entry)
  • func (gl *GroupLogger) LogOuterEntry(entry logging.Entry)
  • func (gl *GroupLogger) Notice(payload interface{})
  • func (gl *GroupLogger) Warning(payload interface{})

Functions

func WithHostname

func WithHostname(labels map[string]string) map[string]string

WithHostname adds the hostname to a labels map. Useful for setting common labels: logging.CommonLabels(WithHostname(labels))

Types

type Client

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

Client adds different Logger generation to Stackdriver's logging.Client.

It can be reused across multiple requests to generate a Logger for each one without repeating auth.

func NewClient

func NewClient(ctx context.Context, parent string, opts ...option.ClientOption) (*Client, error)

NewClient generates a new Client associated with the provided parent.

Options are documented here: https://godoc.org/google.golang.org/api/option#ClientOption

func (*Client) Close

func (client *Client) Close() error

Close waits for all opened GroupLoggers to be flushed and closes the client.

func (*Client) Logger

func (client *Client) Logger(r *http.Request, name string, opts ...logging.LoggerOption) *GroupLogger

Logger constructs and returns a new GroupLogger object for a new group of log entries corresponding to a request R.

Logger options (labels, resources, etc.) are documented here: https://godoc.org/cloud.google.com/go/logging#LoggerOption

func (*Client) Ping

func (client *Client) Ping(ctx context.Context) error

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

func (*Client) SetOnError

func (client *Client) SetOnError(f func(err error))

SetOnError sets the function that is called when an error occurs in a call to Log. This function should be called only once, before any method of Client is called.

Detailed OnError behavior is documented here: https://godoc.org/cloud.google.com/go/logging#Client

type GroupLogger

type GroupLogger struct {
	Req          *http.Request
	GroupID      string
	OuterLogger  *logging.Logger
	InnerLogger  *logging.Logger
	InnerEntries []logging.Entry
}

GroupLogger wraps two Stackdriver Logger clients. The OuterLogger is used to write the entries by which other entries are grouped: usually, these are requests. The InnerLogger is used to write the grouped (enclosed) entries.

These groups are associated in the Stackdriver logging console by their GroupID.

For the inner entries to appear grouped, either `LogOuterEntry` or `CloseWith` must be called.

func (*GroupLogger) Alert

func (gl *GroupLogger) Alert(payload interface{})

Alert logs the payload as an inner entry with severity logging.Alert. Payload must be JSON-marshalable.

func (*GroupLogger) Close

func (gl *GroupLogger) Close()

Close calls CloseWith without specifying statistics. It does not close the client that generated the GroupLogger.

Latency, status, response size, etc. are set to 0 or nil.

func (*GroupLogger) CloseWith

func (gl *GroupLogger) CloseWith(stats *logging.HTTPRequest)

CloseWith decorates the group's base request with the GroupID and with the maximum severity of the inner entries logged so far. It does not close the client that generated the GroupLogger.

If LogOuterEntry is not called, nothing from this group will appear in the outer log.

func (*GroupLogger) Critical

func (gl *GroupLogger) Critical(payload interface{})

Critical logs the payload as an inner entry with severity logging.Critical. Payload must be JSON-marshalable.

func (*GroupLogger) Debug

func (gl *GroupLogger) Debug(payload interface{})

Debug logs the payload as an inner entry with severity logging.Debug. Payload must be JSON-marshalable.

func (*GroupLogger) Default

func (gl *GroupLogger) Default(payload interface{})

Default logs the payload as an inner entry with severity logging.Default. Payload must be JSON-marshalable.

func (*GroupLogger) Emergency

func (gl *GroupLogger) Emergency(payload interface{})

Emergency logs the payload as an inner entry with severity logging.Emergency. Payload must be JSON-marshalable.

func (*GroupLogger) Error

func (gl *GroupLogger) Error(payload interface{})

Error logs the payload as an inner entry with severity logging.Error. Payload must be JSON-marshalable.

func (*GroupLogger) Info

func (gl *GroupLogger) Info(payload interface{})

Info logs the payload as an inner entry with severity logging.Info. Payload must be JSON-marshalable.

func (*GroupLogger) Log

func (gl *GroupLogger) Log(e logging.Entry)

Log logs the payload as an inner entry with severity logging.Default. Payload must be JSON-marshalable.

func (*GroupLogger) LogInnerEntry

func (gl *GroupLogger) LogInnerEntry(entry logging.Entry)

LogInnerEntry pushes an inner log entry for the group, decorated with the GroupID.

func (*GroupLogger) LogOuterEntry

func (gl *GroupLogger) LogOuterEntry(entry logging.Entry)

LogOuterEntry pushes the top-level log entry for the group, decorated with the GroupID.

For the group to be grouped in the GCP logging console, ENTRY must have entry.HTTPRequest set.

func (*GroupLogger) Notice

func (gl *GroupLogger) Notice(payload interface{})

Notice logs the payload as an inner entry with severity logging.Notice. Payload must be JSON-marshalable.

func (*GroupLogger) Warning

func (gl *GroupLogger) Warning(payload interface{})

Warning logs the payload as an inner entry with severity logging.Warning. Payload must be JSON-marshalable.