stackdriver

README

logrus-stackdriver-formatter

logrus formatter for Stackdriver.
Fork from TV4's formatter.

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/shortcut/logrus-stackdriver-formatter

Usage

package main

import (
    "github.com/sirupsen/logrus"
    stackdriver "github.com/shortcut/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/shortcut/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

• Constants
• 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
• 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

Constants

const (
	KeyTrace       = "trace"
	KeySpanID      = "spanID"
	KeyHTTPRequest = "httpRequest"
	KeyLogID       = "logID"
)

Known keys

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"`
	HTTPRequest *HTTPRequest `json:"httpRequest,omitempty"`
	// TraceID string, Optional. Same as TraceID, but without the project-path.
	// Example:
	// 06796866738c859f2f19b7cfb3214824
	TraceID string `json:"trace_id,omitempty"`
	// Trace string
	// Optional. Resource name of the trace associated with the log entry, if any.
	// If it contains a relative resource name, the name is assumed to be relative to tracing.googleapis.com.
	// Example:
	// projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824
	Trace string `json:"logging.googleapis.com/trace,omitempty"`
	// Span string
	// Optional. The span ID within the trace associated with the log entry.
	// For Trace spans, this is the same format that the Trace API v2 uses: a 16-character hexadecimal encoding of an 8-byte array.
	// Example:
	// 000000000000004a
	SpanID         string          `json:"logging.googleapis.com/spanId,omitempty"`
	ServiceContext *ServiceContext `json:"serviceContext,omitempty"`
	Message        string          `json:"message,omitempty"`
	Severity       severity        `json:"severity,omitempty"`
	Context        *Context        `json:"context,omitempty"`
	SourceLocation *ReportLocation `json:"sourceLocation,omitempty"`
}

Entry stores a log entry. More information here: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry

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

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"`
	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:"filePath,omitempty"`
	LineNumber   int    `json:"lineNumber,omitempty"`
	FunctionName string `json:"functionName,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.