yall

Documentation

Index

• Constants
• func InContext(ctx context.Context, l *Logger) context.Context
• type Entry
• type HTTPRequest
• type Logger
  • func FromContext(ctx context.Context) *Logger
  • func New(s Sink) *Logger
  • func (l *Logger) Debug(msg string)
  • func (l *Logger) EndRequest(status int, responseSize int64) *Logger
  • func (l *Logger) Entry(sev Severity) Entry
  • func (l *Logger) Error(msg string)
  • func (l *Logger) Info(msg string)
  • func (l *Logger) StartRequest() *Logger
  • func (l *Logger) Warn(msg string)
  • func (l *Logger) WithError(err error) *Logger
  • func (l *Logger) WithField(k string, v interface{}) *Logger
  • func (l *Logger) WithLabel(k, v string) *Logger
  • func (l *Logger) WithLocalIP(ip string) *Logger
  • func (l *Logger) WithProxyHops(n int) *Logger
  • func (l *Logger) WithRequest(r *http.Request) *Logger
  • func (l *Logger) WithUser(id string) *Logger
• type Severity
• type Sink
• type SinkWithTestHelper

Constants

const (
	// Default is the level entries that don't specify
	// a severity get logged at.
	Default = Severity("DEFAULT")
	// Debug is useful for debugging, but is probably too noisy for standard
	// operation.
	Debug = Severity("DEBUG")
	// Info is routine information that does not indicate an error, but will
	// be helpful to non-debugging operators.
	Info = Severity("INFO")
	// Warning indicates a problem may have occurred, it is unclear. No
	// user-facing errors should occur from events that merit Warning, but
	// those events often predict a future error.
	Warning = Severity("WARN")
	// Error indicates a user-facing error occurred. Error logs that show up
	// repeatedly should lead to issue reports, which should lead to fixes.
	Error = Severity("ERROR")
)

Functions

func InContext

func InContext(ctx context.Context, l *Logger) context.Context

Types

type Entry

type Entry struct {
	// LoggedAt is the time the entry was created. If zero, the current time is used.
	LoggedAt time.Time

	// Severity is the entry's severity level.
	// The zero value is Default.
	Severity Severity

	// Payload is a structured set of data to send as the log entry.
	Payload map[string]interface{}

	// Labels optionally specifies key/value metadata for the log entry.
	Labels map[string]string

	// HTTPRequest optionally specifies metadata about the HTTP request
	// associated with this log entry, if applicable. It is optional.
	HTTPRequest *HTTPRequest

	// Error specifies information about an error
	Error struct {
		// Error is the error being logged.
		Err error
		// Stacktrace is the stacktrace--including the error.
		Stacktrace string
	}

	// User specifies the user the request was made on behalf of.
	User string
}

Entry is a single log event, consisting of structured data and metadata.

type HTTPRequest

type HTTPRequest struct {
	// Request is the http.Request passed to the handler.
	Request *http.Request

	// RequestSize is the size of the HTTP request message in bytes, including
	// the request headers and the request body.
	RequestSize int64

	// Status is the response code indicating the status of the response.
	// Examples: 200, 404.
	Status int

	// ResponseSize is the size of the HTTP response message sent back to the client, in bytes,
	// including the response headers and the response body.
	ResponseSize int64

	// Latency is the request processing latency on the server, from the time the request was
	// received until the response was sent.
	Latency time.Duration

	// LocalIP is the IP address (IPv4 or IPv6) of the origin server that the request
	// was sent to.
	LocalIP string

	// RemoteIP is the IP address (IPv4 or IPv6) of the client that issued the
	// HTTP request. Examples: "192.168.1.1", "FE80::0202:B3FF:FE1E:8329".
	RemoteIP string

	// CacheHit reports whether an entity was served from cache (with or without
	// validation).
	CacheHit bool

	// CacheValidatedWithOriginServer reports whether the response was
	// validated with the origin server before being served from cache. This
	// field is only meaningful if CacheHit is true.
	CacheValidatedWithOriginServer bool

	// CacheFillBytes is the number of HTTP response bytes inserted into
	// cache. Set only when a cache fill was attempted.
	CacheFillBytes int64

	// CacheLookup tells whether or not a cache lookup was attempted.
	CacheLookup bool
}

HTTPRequest defines metadata for an HTTP request associated with an entry.

type Logger

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

func FromContext

func FromContext(ctx context.Context) *Logger

func New

func New(s Sink) *Logger

func (*Logger) Debug

func (l *Logger) Debug(msg string)

func (*Logger) EndRequest

func (l *Logger) EndRequest(status int, responseSize int64) *Logger

func (*Logger) Entry

func (l *Logger) Entry(sev Severity) Entry

func (*Logger) Error

func (l *Logger) Error(msg string)

func (*Logger) Info

func (l *Logger) Info(msg string)

func (*Logger) StartRequest

func (l *Logger) StartRequest() *Logger

func (*Logger) Warn

func (l *Logger) Warn(msg string)

func (*Logger) WithError

func (l *Logger) WithError(err error) *Logger

func (*Logger) WithField

func (l *Logger) WithField(k string, v interface{}) *Logger

func (*Logger) WithLabel

func (l *Logger) WithLabel(k, v string) *Logger

func (*Logger) WithLocalIP

func (l *Logger) WithLocalIP(ip string) *Logger

func (*Logger) WithProxyHops

func (l *Logger) WithProxyHops(n int) *Logger

func (*Logger) WithRequest

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

func (*Logger) WithUser

func (l *Logger) WithUser(id string) *Logger

type Severity

type Severity string

Severity represents a log severity. It's best to use one of the defined constants.

type Sink

type Sink interface {
	AddEntry(Entry)
	Flush() error
}

Sink is something that can take log entries and persist them, either to a datastore or to the user's screen, or discard them.

type SinkWithTestHelper

type SinkWithTestHelper interface {
	Sink
	TestHelper() testing.T
}

SinkWithTestHelper is a special kind of Sink that uses the testing.T type. We make it special because any Sink that fills this interface will have the Helper method called on the testing.T that's returned inside yall, marking the logging functions as helpers so the log line numbers are correctly reported in the output.