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) 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) WithOutput(w io.Writer) *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) 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) WithOutput

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

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

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"`
}

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