sklog

Documentation

Index

• Constants
• Variables
• func AddLogsRedirect(r *mux.Router)
• func CloudLogError(reportName string, err error)
• func CustomLog(reportName string, payload *LogPayload)
• func Debug(msg ...interface{})
• func Debugf(format string, v ...interface{})
• func DebugfWithDepth(depth int, format string, v ...interface{})
• func Debugln(msg ...interface{})
• func Error(msg ...interface{})
• func Errorf(format string, v ...interface{})
• func ErrorfWithDepth(depth int, format string, v ...interface{})
• func Errorln(msg ...interface{})
• func Fatal(msg ...interface{})
• func Fatalf(format string, v ...interface{})
• func FatalfWithDepth(depth int, format string, v ...interface{})
• func Fatalln(msg ...interface{})
• func Flush()
• func FmtErrorf(fmtStr string, args ...interface{}) error
• func Info(msg ...interface{})
• func Infof(format string, v ...interface{})
• func InfofWithDepth(depth int, format string, v ...interface{})
• func Infoln(msg ...interface{})
• func InitCloudLogging(c *http.Client, logGrouping, defaultReport string, ...) error
• func LogLink() string
• func NewCloudLogger(ctx context.Context, projectId, logId string, ts oauth2.TokenSource, ...) (*cloudLogger, error)
• func PostInitCloudLogging(c *http.Client, metricsCallback MetricsCallback) error
• func PreInitCloudLogging(logGrouping, defaultReport string) error
• func SetCloudLoggerForTesting(c CloudLogger)
• func SetLogger(lg CloudLogger)
• func SetMetricsCallback(metricsCallback MetricsCallback)
• func Warning(msg ...interface{})
• func Warningf(format string, v ...interface{})
• func WarningfWithDepth(depth int, format string, v ...interface{})
• func Warningln(msg ...interface{})
• type CloudLogger
  • func CloudLoggingInstance() CloudLogger
  • func GetLogger() CloudLogger
• type LogPayload
• type MetricsCallback

Constants

const (
	CLOUD_LOGGING_WRITE_SCOPE = logging.LoggingWriteScope
	CLOUD_LOGGING_READ_SCOPE  = logging.LoggingReadScope

	// RFC3339NanoZeroPad fixes time.RFC3339Nano which only uses as many
	// sub-second digits are required to represent the time, which makes it
	// unsuitable for sorting.  This format ensures that all 9 nanosecond digits
	// are used, padding with zeroes if necessary.
	RFC3339NanoZeroPad = "2006-01-02T15:04:05.000000000Z07:00"

	// CLOUD_LOGGING_URL_FORMAT is the URL, where first string is defaultReport, second is logGrouping
	CLOUD_LOGGING_URL_FORMAT = "" /* 139-byte string literal not displayed */

	// WRITE_LOG_ENTRIES_REQUEST_TIMEOUT is the Timeout for making the WriteLogEntriesRequest request.
	WRITE_LOG_ENTRIES_REQUEST_TIMEOUT = time.Second

	// MAX_QPS_LOG is the max number of log lines we expect to generate per second.
	MAX_QPS_LOG = 10000

	// LOG_WRITE_SECONDS is the time between batch writes to cloud logging, in seconds.
	LOG_WRITE_SECONDS = 5

	// MAX_LOG_SIZE is the max number of log entries we keep locally.
	MAX_LOG_SIZE = LOG_WRITE_SECONDS * MAX_QPS_LOG

	// REQ_SIZE_BASE is the approximate base size in bytes of an empty log
	// push request in bytes.
	REQ_SIZE_BASE = 128

	// REQ_SIZE_MAX is the maximum size in bytes of a log push request. Give
	// ourselves 20% headroom just in case our estimates are incorrect.
	REQ_SIZE_MAX = int(10485760.0 * 0.80)

	// ENTRY_SIZE_BASE is the approximate size in bytes of a serialized
	// empty LogEntry object.
	ENTRY_SIZE_BASE = 512

	// ENTRY_SIZE_MAX is the maximum size in bytes of a serialized LogEntry
	// object. Give ourselves 20% headroom just in case our estimates are
	// incorrect.
	ENTRY_SIZE_MAX = int(112640.0 * 0.80)

	// PAYLOAD_SIZE_MAX is the approximate maximum log line size in bytes.
	PAYLOAD_SIZE_MAX = ENTRY_SIZE_MAX - ENTRY_SIZE_BASE
)

There a variety of Log Entry types, but for simplicity, we have stuck with the "text payload" option

const (
	// Severities used primarily by Cloud Logging.
	DEBUG    = "DEBUG"
	INFO     = "INFO"
	NOTICE   = "NOTICE"
	WARNING  = "WARNING"
	ERROR    = "ERROR"
	CRITICAL = "CRITICAL"
	ALERT    = "ALERT"

	// Template used to build log links.
	LOG_LINK_TMPL = "" /* 159-byte string literal not displayed */

	// PROJECT_ID is defined here instead of in go/common to prevent an
	// import cycle.
	PROJECT_ID = "google.com:skia-buildbots"

	// b/120145392
	KUBERNETES_FILE_LINE_NUMBER_WORKAROUND = true
)

Variables

var (

	// AllSeverities is the list of all severities that sklog supports.
	AllSeverities = []string{
		DEBUG,
		INFO,
		NOTICE,
		WARNING,
		ERROR,
		CRITICAL,
		ALERT,
	}
)

Functions

func AddLogsRedirect

func AddLogsRedirect(r *mux.Router)

AddLogsRedirect adds an endpoint which redirects to the GCloud log page for this process at /logs.

func CloudLogError

func CloudLogError(reportName string, err error)

CloudLogError writes an error to CloudLogging if the global logger has been set. Otherwise, it just prints it using glog.

func CustomLog

func CustomLog(reportName string, payload *LogPayload)

CustomLog allows any clients to write a LogPayload to a report with a custom group name (e.g. "log file name"). This is the simplist way for an app to send logs to somewhere other than the default report name (typically based on the app-name).

func Debug

func Debug(msg ...interface{})

These convenience methods will either make a Cloud Logging Entry using the current time and the default report name associated with the CloudLogger or log to glog if Cloud Logging is not configured. They are a superset of the glog interface. Info and Infoln do the same thing (as do all pairs), because adding a newline to the end of a Cloud Logging Entry or a glog entry means nothing as all logs are separate entries. InfofWithDepth allow the caller to change where the stacktrace starts. 0 (the default in all other calls) means to report starting at the caller. 1 would mean one level above, the caller's caller. 2 would be a level above that and so on.

func Debugf

func Debugf(format string, v ...interface{})

func DebugfWithDepth

func DebugfWithDepth(depth int, format string, v ...interface{})

func Debugln

func Debugln(msg ...interface{})

func Error

func Error(msg ...interface{})

func Errorf

func Errorf(format string, v ...interface{})

func ErrorfWithDepth

func ErrorfWithDepth(depth int, format string, v ...interface{})

func Errorln

func Errorln(msg ...interface{})

func Fatal

func Fatal(msg ...interface{})

Fatal* uses an ALERT Cloud Logging Severity and then panics, similar to glog.Fatalf() In Fatal*, there is no callback to sawLogWithSeverity, as the program will soon exit and the counter will be reset to 0.

func Fatalf

func Fatalf(format string, v ...interface{})

func FatalfWithDepth

func FatalfWithDepth(depth int, format string, v ...interface{})

func Fatalln

func Fatalln(msg ...interface{})

func Flush

func Flush()

func FmtErrorf

func FmtErrorf(fmtStr string, args ...interface{}) error

FmtError is a wrapper around fmt.Errorf that prepends the source location (filename and line number) of the caller.

func Info

func Info(msg ...interface{})

func Infof

func Infof(format string, v ...interface{})

func InfofWithDepth

func InfofWithDepth(depth int, format string, v ...interface{})

func Infoln

func Infoln(msg ...interface{})

func InitCloudLogging

func InitCloudLogging(c *http.Client, logGrouping, defaultReport string, metricsCallback MetricsCallback) error

CLIENTS SHOULD NOT CALL InitCloudLogging directly. Instead use common.InitWithCloudLogging. InitCloudLogging initializes the module-level logger. logGrouping refers to the MonitoredResource's name. If blank, logGrouping defaults to the machine's hostname. defaultReportName refers to the default "virtual log file" name that Log Entries will be associated with if no other reportName is given. If an error is returned, cloud logging will not

be used, instead glog will.

metricsCallback should not call any sklog.* methods, to avoid infinite recursion. InitCloudLogging should be called before the program creates any go routines such that all subsequent logs are properly sent to the Cloud.

func LogLink

func LogLink() string

LogLink returns a link to the logs for this process.

func NewCloudLogger

func NewCloudLogger(ctx context.Context, projectId, logId string, ts oauth2.TokenSource, labels map[string]string) (*cloudLogger, error)

NewCloudLogger returns a CloudLogger instance.

func PostInitCloudLogging

func PostInitCloudLogging(c *http.Client, metricsCallback MetricsCallback) error

PostInitCloudLogging finishes initializing cloud logging.

CLIENTS SHOULD NOT CALL PostInitCloudLogging directly. Instead use common.InitWith().

func PreInitCloudLogging

func PreInitCloudLogging(logGrouping, defaultReport string) error

PreInitCloudLogging does the first step in initializing cloud logging.

CLIENTS SHOULD NOT CALL PreInitCloudLogging directly. Instead use common.InitWith().

func SetCloudLoggerForTesting

func SetCloudLoggerForTesting(c CloudLogger)

SetCloudLoggerForTesting sets the globally available CloudLogger which will be used for reporting errors. This should be used only for mocking.

func SetLogger

func SetLogger(lg CloudLogger)

SetLogger changes the package to use the given CloudLogger.

func SetMetricsCallback

func SetMetricsCallback(metricsCallback MetricsCallback)

SetMetricsCallback sets sawLogWithSeverity.

This is set up to break a dependency cycle, such that sklog does not depend on metrics2.

func Warning

func Warning(msg ...interface{})

func Warningf

func Warningf(format string, v ...interface{})

func WarningfWithDepth

func WarningfWithDepth(depth int, format string, v ...interface{})

func Warningln

func Warningln(msg ...interface{})

Types

type CloudLogger

type CloudLogger interface {
	// CloudLog writes creates a Log Entry from the log payload and sends it to Cloud Logging to be
	// associated with the "virtual log file" given by reportName. Log entries will automatically be
	// labeled with the machine's hostname.
	// Most clients will use the convenience methods in sklog.go. The primary use case for using
	// CloudLog directly is if customizing the reportName, the time, or use one of the less common
	// severities.
	CloudLog(reportName string, payload *LogPayload)

	// BatchCloudLog works like CloudLog, but will send multiple logs at a time.
	BatchCloudLog(reportName string, payloads ...*LogPayload)

	// Wait until any outstanding writes to Cloud Logging have finished.
	Flush()
}

A CloudLogger interacts with the CloudLogging api

func CloudLoggingInstance

func CloudLoggingInstance() CloudLogger

CloudLoggingInstance returns the module-level cloud logger.

func GetLogger

func GetLogger() CloudLogger

GetLogger retrieves the CloudLogger used by this package, if any.

type LogPayload

type LogPayload struct {
	// Payload is the text content of the log file.
	Payload string
	// Time is the when the log happened.
	Time time.Time
	// Severity is one of the strings found in this package, such as DEBUG, ALERT, etc.
	Severity string
	// Any additional labels to be added to this Log Entry. hostname is already included.
	// These labels can be searched on.
	ExtraLabels map[string]string
}

LogPayload represents the contents of a Log Entry with a text payload.

type MetricsCallback

type MetricsCallback func(severity string)