log

README

Log

Formatter for logrus, allowing log entries to be recognized by the fluentd Stackdriver agent on Google Cloud Platform.

Example:

package main

import (
	"time"
	"net/http"

	log "github.com/sirupsen/logrus"
	joonix "github.com/joonix/log"
)

func main() {
	log.SetFormatter(joonix.NewFormatter())
	log.Info("hello world!")

	// log a HTTP request in your handler
	log.WithField("httpRequest", &joonix.HTTPRequest{
		Request: r,
		Status: http.StatusOK,
		ResponseSize: 31337,
		Latency: 123*time.Millisecond,
	}).Info("additional info")
}

Alternatives

• https://github.com/TV4/logrus-stackdriver-formatter (seems abandoned)
• https://github.com/knq/sdhook (implemented as a hook, doesn't require fluentd)
• https://github.com/joonix/log/issues/2 (you can map the format yourself)

Kubernetes logging from outside of GCP

It is possible to run the google edition of fluentd a.k.a. stackdriver agent outside of GCP, just a bit tricky to configure. See following references for more info:

• Fluentd build: https://github.com/GoogleCloudPlatform/k8s-stackdriver/tree/master/fluentd-gcp-image
• Manifest examples: https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/fluentd-gcp
• Manifest vars (fluentd_gcp_yaml_version): https://github.com/kubernetes/kubernetes/blob/master/cluster/gce/config-default.sh
• Tutorial (old manifest): https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/

Documentation

Index

• Variables
• func DisableTimestampFormat(f *Formatter) error
• func PrettyPrintFormat(f *Formatter) error
• func StackdriverFormat(f *Formatter) error
• type Format
• type Formatter
  • func NewFormatter(opts ...Format) *Formatter
  • func (f *Formatter) Format(entry *logrus.Entry) ([]byte, error)
• type HTTPRequest
  • func (r HTTPRequest) MarshalJSON() ([]byte, error)

Variables

var DefaultFormat = StackdriverFormat

DefaultFormat is Stackdriver.

Functions

func DisableTimestampFormat

func DisableTimestampFormat(f *Formatter) error

func PrettyPrintFormat

func PrettyPrintFormat(f *Formatter) error

func StackdriverFormat

func StackdriverFormat(f *Formatter) error

StackdriverFormat maps values to be recognized by the Google Cloud Platform. https://cloud.google.com/logging/docs/agent/configuration#special-fields

Types

type Format

type Format func(*Formatter) error

Format configuration of the logrus formatter output.

type Formatter

type Formatter struct {
	// DisableTimestamp allows disabling automatic timestamps in output
	DisableTimestamp bool

	// TimestampFormat sets the format used for marshaling timestamps.
	TimestampFormat func(logrus.Fields, time.Time) error

	// SeverityMap allows for customizing the names for keys of the log level field.
	SeverityMap map[string]string

	// PrettyPrint will indent all json logs
	PrettyPrint bool
}

Formatter that is called on by logrus.

func NewFormatter

func NewFormatter(opts ...Format) *Formatter

NewFormatter with optional options. Defaults to the Stackdriver option.

func (*Formatter) Format

func (f *Formatter) Format(entry *logrus.Entry) ([]byte, error)

Format the log entry. Implements logrus.Formatter.

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
}

HTTPRequest contains an http.Request as well as additional information about the request and its response. https://github.com/googleapis/google-cloud-go/blob/v0.39.0/logging/logging.go#L617

func (HTTPRequest) MarshalJSON

func (r HTTPRequest) MarshalJSON() ([]byte, error)