logger

README

teltech/logger

Super simple structured logging mechanism for Go projects with Stackdriver format compatibility

Installation

go get -u github.com/teltech/logger

Usage

package main

import (
    "github.com/teltech/logger"
)

// There should be a LOG_LEVEL environment variable set, which is read by the library
// If no value is set, the default LOG_LEVEL will be INFO

func main() {
    // Stackdriver requires a project name and version to be set. Use your environment for these values.
    // SERVICE should be your GCP project-id, e.g. my-gce-project-id
    // VERSION is an arbitrary value
    log := logger.New()

    // You can also initialize the logger with a context, the values will persisted throughout the scope of the logger instance
    log = logger.New().With(logger.Fields{
        "user":   "+1234567890",
        "action": "create-account",
    })

    param := "something useful here"

    // Log a DEBUG message, only visible in when LOG_LEVEL is set to DEBUG
    log.With(logger.Fields{"key": "val", "something": true}).Debug("debug message goes here")
    log.With(logger.Fields{"key": "val"}).Debugf("debug message with %s", param)

    // Log an INFO message, should be used for metrics as well
    log.Info("CUSTOM_METRIC")
    log.With(logger.Fields{"key": "val", "names": []string{"Mauricio", "Manuel"}}).Info("info message goes here")
    log.With(logger.Fields{"key": "val"}).Infof("info message with %s", param)

    // Log a WARN message
    log.With(logger.Fields{"key": "val"}).Warn("warn message goes here")
    log.With(logger.Fields{"key": "val"}).Warnf("warn message with %s", param)

    // Error() prints the stacktrace as part of the payload for each entry and sends the
    // data to Stackdriver Error Reporting service
    log.With(logger.Fields{"key": "val"}).Error("error message goes here")
    log.With(logger.Fields{"key": "val"}).Errorf("error message with %s", param)
}

Output

The errors require a specific JSON format for them to be ingested and processed by Google Cloud Platform Stackdriver Logging and Error Reporting. See: https://cloud.google.com/error-reporting/docs/formatting-error-messages. The resulting output has the following format, optional fields are... well, optional:

       {
          "severity": "ERROR",
          "eventTime": "2017-04-26T02:29:33-04:00",
          "message": "An error just happened!",
          "serviceContext": {
             "service": "my-gce-project-id",
             "version": "1.0"
          },
          "context": {
            "data": {
              "clientIP": "127.0.0.1",
              "userAgent": "Mosaic 1.0"
            },
            "reportLocation": {
              "filePath": "\/Users\/mc\/Documents\/src\/github.com\/macuenca\/apex\/mauricio.go",
              "functionName": "unknown",
              "lineNumber": 15
            }
          },
         "stacktrace": "goroutine 1 [running]:main.main()\n\t\/github.com\/macuenca\/mauricio.go:15 +0x1a9\n"
       }

License

This package is licensed under the BSD 3-clause license.

Documentation

Index

• Constants
• type Context
• type Fields
• type Log
  • func New() *Log
  • func (l *Log) AddCallerSkip(skip int)
  • func (l *Log) Debug(message string)
  • func (l *Log) Debugf(message string, args ...interface{})
  • func (l *Log) Error(message string)
  • func (l *Log) Errorf(message string, args ...interface{})
  • func (l *Log) Fatal(message string)
  • func (l *Log) Fatalf(message string, args ...interface{})
  • func (l *Log) Info(message string)
  • func (l *Log) Infof(message string, args ...interface{})
  • func (l *Log) Warn(message string)
  • func (l *Log) Warnf(message string, args ...interface{})
  • func (l *Log) With(fields Fields) *Log
  • func (l *Log) WithLevel(logLevel severity) *Log
  • func (l *Log) WithOutput(w io.Writer) *Log
  • func (l *Log) WithTrace(traceID string, spanID string, sampled bool, projectName string) *Log
• type Payload
• type ReportLocation
• type ServiceContext

Constants

const (
	DEBUG severity = iota
	INFO
	WARN
	ERROR
	CRITICAL
)

Types

type Context

type Context struct {
	Data           Fields          `json:"data,omitempty"`
	ReportLocation *ReportLocation `json:"reportLocation,omitempty"`
}

Context is required by the Stackdriver Error format

type Fields

type Fields map[string]interface{}

Fields is used to wrap the log entries payload

type Log

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

Log is the main type for the logger package

func New

func New() *Log

New instantiates and returns a Log object

func (*Log) AddCallerSkip

func (l *Log) AddCallerSkip(skip int)

AddCallerSkip increases the number of callers skipped by caller annotation. When building wrappers around the Logger, supplying this value prevents logger from always reporting the wrapper code as the caller.

func (*Log) Debug

func (l *Log) Debug(message string)

Debug prints out a message with DEBUG severity level

func (*Log) Debugf

func (l *Log) Debugf(message string, args ...interface{})

Debugf prints out a message with DEBUG severity level

func (*Log) Error

func (l *Log) Error(message string)

Error prints out a message with ERROR severity level

func (*Log) Errorf

func (l *Log) Errorf(message string, args ...interface{})

Errorf prints out a message with ERROR severity level

func (*Log) Fatal

func (l *Log) Fatal(message string)

Fatal is equivalent to Error() followed by a call to os.Exit(1). It prints out a message with CRITICAL severity level

func (*Log) Fatalf

func (l *Log) Fatalf(message string, args ...interface{})

Fatalf is equivalent to Errorf() followed by a call to os.Exit(1). It prints out a message with CRITICAL severity level

func (*Log) Info

func (l *Log) Info(message string)

Info prints out a message with INFO severity level

func (*Log) Infof

func (l *Log) Infof(message string, args ...interface{})

Infof prints out a message with INFO severity level

func (*Log) Warn

func (l *Log) Warn(message string)

Warn prints out a message with WARN severity level

func (*Log) Warnf

func (l *Log) Warnf(message string, args ...interface{})

Warnf prints out a message with WARN severity level

func (*Log) With

func (l *Log) With(fields Fields) *Log

With is used as a chained method to specify which values go in the log entry's context

func (*Log) WithLevel

func (l *Log) WithLevel(logLevel severity) *Log

WithLevel creates a copy of a Log with a different log level

func (*Log) WithOutput

func (l *Log) WithOutput(w io.Writer) *Log

WithOutput creates a copy of a Log with a different output.

func (*Log) WithTrace

func (l *Log) WithTrace(traceID string, spanID string, sampled bool, projectName string) *Log

WithTrace creates a copy of a Log with added trace properties

type Payload

type Payload struct {
	Severity       string          `json:"severity"`
	EventTime      string          `json:"eventTime"`
	Caller         string          `json:"caller,omitempty"`
	Message        string          `json:"message"`
	ServiceContext *ServiceContext `json:"serviceContext,omitempty"`
	Context        *Context        `json:"context,omitempty"`
	Stacktrace     string          `json:"stacktrace,omitempty"`
	// contains filtered or unexported fields
}

Payload groups all the data for a log entry

type ReportLocation

type ReportLocation struct {
	FilePath     string `json:"filePath"`
	FunctionName string `json:"functionName"`
	LineNumber   int    `json:"lineNumber"`
}

ReportLocation is required by the Stackdriver Error format

type ServiceContext

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

ServiceContext is required by the Stackdriver Error format