stackdriver

README

logrus-stackdriver-formatter

logrus formatter for Stackdriver.

In addition to supporting level-based logging to Stackdriver, for Error, Fatal and Panic levels it will append error context for Error Reporting.

Installation

go get -u github.com/TV4/logrus-stackdriver-formatter

Usage

package main

import (
    "github.com/sirupsen/logrus"
    stackdriver "github.com/TV4/logrus-stackdriver-formatter"
)

var log = logrus.New()

func init() {
    log.Formatter = stackdriver.NewFormatter(
        stackdriver.WithService("your-service"), 
        stackdriver.WithVersion("v0.1.0"),
    )
    log.Level = logrus.DebugLevel

    log.Info("ready to log!")
}

Here's a sample entry (prettified) from the example:

{
  "serviceContext": {
    "service": "test-service",
    "version": "v0.1.0"
  },
  "message": "unable to parse integer: strconv.ParseInt: parsing \"text\": invalid syntax",
  "severity": "ERROR",
  "context": {
    "reportLocation": {
      "filePath": "github.com/TV4/logrus-stackdriver-formatter/example_test.go",
      "lineNumber": 21,
      "functionName": "ExampleLogError"
    }
  }
}

HTTP request context

If you'd like to add additional context like the httpRequest, here's a convenience function for creating a HTTP logger:

func httpLogger(logger *logrus.Logger, r *http.Request) *logrus.Entry {
    return logger.WithFields(logrus.Fields{
        "httpRequest": map[string]interface{}{
            "method":    r.Method,
            "url":       r.URL.String(),
            "userAgent": r.Header.Get("User-Agent"),
            "referrer":  r.Header.Get("Referer"),
        },
    })
}

Then, in your HTTP handler, create a new context logger and all your log entries will have the HTTP request context appended to them:

func handler(w http.ResponseWriter, r *http.Request) {
    httplog := httpLogger(log, r)
    // ...
    httplog.Infof("Logging with HTTP request context")
}

Documentation

Index

• func InitLogging() *logrus.Logger
• func LoggingMiddleware(log *logrus.Logger) func(http.Handler) http.Handler
• type Context
• type Entry
• type Formatter
  • func NewFormatter(options ...Option) *Formatter
  • func (f *Formatter) Format(e *logrus.Entry) ([]byte, error)
  • func (f *Formatter) ToEntry(e *logrus.Entry) (Entry, error)
• type HTTPRequest
• type Option
  • func WithProjectID(i string) Option
  • func WithService(n string) Option
  • func WithStackSkip(v string) Option
  • func WithVersion(v string) Option
• type ReportLocation
• type ServiceContext

Functions

func InitLogging

func InitLogging() *logrus.Logger

InitLogging initializes a logger to send things to stackdriver.

func LoggingMiddleware

func LoggingMiddleware(log *logrus.Logger) func(http.Handler) http.Handler

LoggingMiddleware is a middleware for writing request logs in a stuctured format to stackdriver.

Types

type Context

type Context struct {
	Data           map[string]interface{} `json:"data,omitempty"`
	ReportLocation *ReportLocation        `json:"reportLocation,omitempty"`
	HTTPRequest    *HTTPRequest           `json:"httpRequest,omitempty"`
}

Context is sent with every message to stackdriver.

type Entry

type Entry struct {
	LogName        string          `json:"logName,omitempty"`
	Timestamp      string          `json:"timestamp,omitempty"`
	Severity       severity        `json:"severity,omitempty"`
	HTTPRequest    *HTTPRequest    `json:"httpRequest,omitempty"`
	Trace          string          `json:"trace,omitempty"`
	ServiceContext *ServiceContext `json:"serviceContext,omitempty"`
	Message        string          `json:"message,omitempty"`
	Context        *Context        `json:"context,omitempty"`
	SourceLocation *ReportLocation `json:"sourceLocation,omitempty"`
}

Entry stores a log entry.

type Formatter

type Formatter struct {
	Service   string
	Version   string
	ProjectID string
	StackSkip []string
}

Formatter implements Stackdriver formatting for logrus.

func NewFormatter

func NewFormatter(options ...Option) *Formatter

NewFormatter returns a new Formatter.

func (*Formatter) Format

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

Format formats a logrus entry according to the Stackdriver specifications.

func (*Formatter) ToEntry

func (f *Formatter) ToEntry(e *logrus.Entry) (Entry, error)

ToEntry formats a logrus entry to a stackdriver entry.

type HTTPRequest

type HTTPRequest struct {
	RequestMethod                  string `json:"requestMethod,omitempty"`
	RequestURL                     string `json:"requestUrl,omitempty"`
	RequestSize                    string `json:"requestSize,omitempty"`
	Status                         string `json:"status,omitempty"`
	ResponseSize                   string `json:"responseSize,omitempty"`
	UserAgent                      string `json:"userAgent,omitempty"`
	RemoteIP                       string `json:"remoteIp,omitempty"`
	ServerIP                       string `json:"serverIp,omitempty"`
	Referer                        string `json:"referer,omitempty"`
	Latency                        string `json:"latency,omitempty"`
	CacheLookup                    bool   `json:"cacheLookup,omitempty"`
	CacheHit                       bool   `json:"cacheHit,omitempty"`
	CacheValidatedWithOriginServer bool   `json:"cacheValidatedWithOriginServer,omitempty"`
	CacheFillBytes                 string `json:"cacheFillBytes,omitempty"`
	Protocol                       string `json:"protocol,omitempty"`
}

HTTPRequest defines details of a request and response to append to a log.

type Option

type Option func(*Formatter)

Option lets you configure the Formatter.

func WithProjectID

func WithProjectID(i string) Option

WithProjectID makes sure all entries have your Project information.

func WithService

func WithService(n string) Option

WithService lets you configure the service name used for error reporting.

func WithStackSkip

func WithStackSkip(v string) Option

WithStackSkip lets you configure which packages should be skipped for locating the error.

func WithVersion

func WithVersion(v string) Option

WithVersion lets you configure the service version used for error reporting.

type ReportLocation

type ReportLocation struct {
	FilePath     string `json:"file,omitempty"`
	LineNumber   int    `json:"line,omitempty"`
	FunctionName string `json:"function,omitempty"`
}

ReportLocation is the information about where an error occurred.

type ServiceContext

type ServiceContext struct {
	Service string `json:"service,omitempty"`
	Version string `json:"version,omitempty"`
}

ServiceContext provides the data about the service we are sending to Google.