stackdriver

README

Stackdriver GAE Logrus Plugin

Logrus is a structured logger for Go compatible with the standard library logger.

Stackdriver GAE Logrus Plugin is a lightweight plugin providing threaded message entries on Google Cloud Run and Google App Engine (GAE) Standard Environment.

Cloud Run and GAE adds a request header X-Cloud-Trace-Context to HTTP requests. middleware.XCloudTraceContext provides an HTTP Middleware component that parses this header and make it available in the context.

contextLogger := log.WithContext(r.Context())

contextLogger.WithFields(log.Fields{
	"battery": "50",
}).Debug("Flux capacitor low")

contextLogger.WithFields(log.Fields{
	"status": "busted",
}).Info("Warp speed activated")

contextLogger.WithFields(log.Fields{
	"status": "hmmm",
}).Warn("You have been warning")

contextLogger.WithFields(log.Fields{
	"status": "busted",
}).Error("These are not the drones you are looking for")

In the Stack Driver Logging Cloud Console you can filter results by request.

Opening an individual request will show each log entry nested within. Each entry will have a color coded icon showing its severity corrsponding to its nearest equivilent Logrus level.

Whilst debugging select any individual log message's trace value and click "Show matching entries".

This will automatically set the filters to reveal all log entries associated to that HTTP request.

Clicking the discover icon expands the log entry to reveal the jsonPayload section. jsonPayload.data contains the field data set using the standard Logrus WithFields method.

contextLogger.WithFields(log.Fields{
	"status": "busted",
}).Error("These are not the drones you are looking for")

To run the example locally use:

make run

Windows

If you do not have Make installed.

go run ./examples/http-service/main.go

Limitations

The Trace ID and Span ID can be attained using either the Traceparent header (v2), or the X-Cloud-Trace-Context header (v1). Google App Engine and Google Cloud Run use hexadecimal trace and span IDs and my understanding is that they intend to do so in the future. As of v0.3.1 the formatter will assume that the trace and span IDs are hexadecimal in the request headers sent by Google App Engine and Google Cloud Run and will format them as such.

v0.3.1 only supports the v1 API.

Acknowledgements

Thanks to csilvers for his contributions that proces the Span ID, as well as his help with understanding how logging works in Google App Engine.

Todo

• Implement a solution based on the Traceparent header and only fallback to X-Cloud-Trace-Context if the Traceparent header is not present.

Documentation

Index

• type Formatter
  • func GAEStandardFormatter(options ...Option) *Formatter
  • func (f *Formatter) Format(e *logrus.Entry) ([]byte, error)
• type Option
  • func WithProjectID(pid string) Option
• type XCTContext

Types

type Formatter

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

Formatter implements threaded Stackdriver formatting for logrus.

func GAEStandardFormatter

func GAEStandardFormatter(options ...Option) *Formatter

GAEStandardFormatter returns a new Formatter.

func (*Formatter) Format

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

Format formats a logrus entry in Stackdriver format.

type Option

type Option func(*Formatter)

Option lets you configure the Formatter.

func WithProjectID

func WithProjectID(pid string) Option

WithProjectID lets you configure the GAE project for threaded messaging.

type XCTContext

type XCTContext string

XCTContext holds the X Cloud Trace Context value