Documentation

Overview

    Package sdlogger is a logger that formats entries as JSON understood by Stackdriver log collectors.

    The JSON format is defined by the Google Cloud Logging plugin for fluentd, which is mainly used by Google Kubernetes Engine + Stackdriver stack. See https://github.com/GoogleCloudPlatform/fluent-plugin-google-cloud

    Though not properly documented, GAE environment also understands subset of this format.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Factory

    func Factory(w LogEntryWriter, prototype LogEntry, mut LogEntryMutator) func(context.Context) logging.Logger

      Factory returns a factory of logger.Logger instances that log to the given LogEntryWriter (usually &Sink{...}) using the LogEntry (if any) as a prototype for log entries.

      For each log message, makes a copy of 'prototype', overwrites its Severity, Message, Time and Fields (keeping other fields as they are), calls 'mut' callback (which is allowed to mutate the log entry), and writes the result to LogEntryWriter. This allows to "prepopulate" fields like TraceID or OperationID in all log entries emitted by logging.Logger.

      Such factory can be installed in the context via logging.SetFactory.

      Types

      type LogEntry

      type LogEntry struct {
      	// Severity is a string denoting the logging level of the entry.
      	Severity Severity `json:"severity"`
      	// Message is a single line human readable string of the log message.
      	Message string `json:"message,omitempty"`
      	// Timestamp is the unix timestamp of when the entry was produced.
      	Timestamp Timestamp `json:"timestamp,omitempty"`
      	// TraceID is 32-byte hex string with Stackdriver trace ID.
      	TraceID string `json:"logging.googleapis.com/trace,omitempty"`
      	// TraceSampled is true if this trace will be uploaded to Stackdriver.
      	TraceSampled bool `json:"logging.googleapis.com/trace_sampled,omitempty"`
      	// SpanID is a 16-byte hex string with Stackdriver span ID.
      	SpanID string `json:"logging.googleapis.com/spanId,omitempty"`
      	// Operation is used to group log lines from a single request together.
      	Operation *Operation `json:"logging.googleapis.com/operation,omitempty"`
      	// RequestInfo is information about the handled HTTP request.
      	RequestInfo *RequestInfo `json:"httpRequest,omitempty"`
      	// Fields are extra structured data that may be tagged in the log entry.
      	Fields logging.Fields `json:"fields,omitempty"`
      }

        LogEntry defines a structure of JSON log entries recognized by google-fluentd plugin on GKE.

        See https://cloud.google.com/logging/docs/agent/configuration#process-payload for a list of possible magical fields. All other fields are exposed as part of jsonPayload in Stackdriver logs.

        type LogEntryMutator

        type LogEntryMutator func(context.Context, *LogEntry)

          LogEntryMutator may mutate log entries before they are written.

          type LogEntryWriter

          type LogEntryWriter interface {
          	// Write appends a log entry to the output.
          	Write(*LogEntry)
          }

            LogEntryWriter knows how to write LogEntries to some output.

            type Operation

            type Operation struct {
            	ID string `json:"id"`
            }

              Operation is used to group log lines from a single request together.

              type RequestInfo

              type RequestInfo struct {
              	Method       string `json:"requestMethod"` // e.g. "GET"
              	URL          string `json:"requestUrl"`    // e.g. "http://host/path"
              	Status       int    `json:"status"`        // e.g. 200
              	RequestSize  string `json:"requestSize"`   // e.g. "123123"
              	ResponseSize string `json:"responseSize"`  // e.g. "2324"
              	UserAgent    string `json:"userAgent"`     // e.g. "Mozilla/4.0 ..."
              	RemoteIP     string `json:"remoteIp"`      // e.g. "192.168.1.1"
              	Latency      string `json:"latency"`       // e.g. "3.5s"
              }

                RequestInfo contains information about handled HTTP request.

                See following definition for all fields we can possibly expose here: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest

                type Severity

                type Severity string

                  Severity is a string denoting the logging level of the entry.

                  Must be one of the predefined constants, otherwise Stackdriver may not recognize it.

                  const (
                  	UnknownSeverity Severity = ""
                  	DebugSeverity   Severity = "DEBUG"
                  	InfoSeverity    Severity = "INFO"
                  	WarningSeverity Severity = "WARNING"
                  	ErrorSeverity   Severity = "ERROR"
                  )

                    All allowed severities. Using other values results in undefined behavior.

                    func LevelToSeverity

                    func LevelToSeverity(l logging.Level) Severity

                      LevelToSeverity converts logging level to the corresponding severity.

                      type SeverityTracker

                      type SeverityTracker struct {
                      	Out LogEntryWriter
                      	// contains filtered or unexported fields
                      }

                        SeverityTracker wraps LogEntryWriter and observes severity of messages there.

                        func (*SeverityTracker) MaxSeverity

                        func (s *SeverityTracker) MaxSeverity() Severity

                          MaxSeverity returns maximum severity observed thus far or "".

                          func (*SeverityTracker) Write

                          func (s *SeverityTracker) Write(l *LogEntry)

                            Write is part of LogEntryWriter interface.

                            type Sink

                            type Sink struct {
                            	Out io.Writer
                            	// contains filtered or unexported fields
                            }

                              Sink takes care of JSON-serializing log entries and synchronizing writes to an io.Writer (usually stdout or stderr).

                              Implements LogEntryWriter.

                              Sink can either be used directly for fine-grain control of what is getting logged, or via a logging.Logger for interoperability with most of LUCI code.

                              There should be at most one Sink instance assigned to a given io.Writer, shared by all Logger instances writing to it. Violating this requirement may cause malformed log lines.

                              func (*Sink) Write

                              func (s *Sink) Write(l *LogEntry)

                                Write appends a log entry to the output by JSON-serializing and writing it.

                                Panics if the LogEntry can't be serialized (this should not be possible). Ignores errors from io.Writer.

                                type Timestamp

                                type Timestamp struct {
                                	Seconds int64 `json:"seconds"`
                                	Nanos   int64 `json:"nanos"`
                                }

                                  Timestamp represents a unix timestamp.

                                  func ToTimestamp

                                  func ToTimestamp(t time.Time) Timestamp

                                    ToTimestamp converts time.Time to Timestamp.