logz

README

Logz - yet another logger library for go

The logz is logger library for grouping application logs related a access log. The logz uses OpenTelemetry(https://opentelemetry.io) to generate the trace id.
This is for Google Cloud Logging (formerly known as Stackdriver Logging).

Features

• Writes access log each http requests
• Writes application log
• Grouping application logs related a access log.
  • The parent entry will inherit the severity of its children
• Supports to App Engine 2nd and Cloud Run and GKE.

Use go111 package if your project is App Engine 1st generation.

Contribution Packages

The logz contribution packages that provides middlewares for 3rd-party Go packages.

• gin
• echo
• gRPC

For more details: https://github.com/devotedalpha/logz/tree/main/contrib

Install

$ go get github.com/devotedalpha/logz

Usage

Google App Engine Standard

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        // Writes info log
        logz.Infof(ctx, "writes %s log", "info")
    })

    logz.SetConfig(logz.Config{
        NeedsAccessLog: true, // Writes the access log
    })
    logz.InitTracer()
    // Sets the middleware
    h := middleware.NetHTTP("tracer name")(mux)

    log.Fatal(http.ListenAndServe(":8080", h))
}

Cloud Run

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        // Writes info log
        logz.Infof(ctx, "writes %s log", "info")
    })

    logz.SetConfig(logz.Config{
        ProjectID:       "your gcp project id",
        NeedsAccessLog: false, // Writes no access log
    })
    logz.InitTracer()
    // Sets the middleware
    h := middleware.NetHTTP("tracer name")(mux)

    log.Fatal(http.ListenAndServe(":8080", h))
}

GKE

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        // Writes info log
        logz.Infof(ctx, "writes %s log", "info")
    })

    logz.SetConfig(logz.Config{
        ProjectID:       "your gcp project id",
        NeedsAccessLog: true, // Writes the access log
    })
    logz.InitTracer()
    // Sets the middleware
    h := middleware.NetHTTP("tracer name")(mux)

    log.Fatal(http.ListenAndServe(":8080", h))
}

Examples

See this sample projects for logz detailed usage
https://github.com/devotedalpha/logz/tree/main/example

How logs are grouped

The logz leverages the grouping feature of GCP Cloud Logging. See following references for more details.

• https://godoc.org/cloud.google.com/go/logging#hdr-Grouping_Logs_by_Request

Log format

The log format is based on LogEntry's structured payload

Application log format

{
  "severity":"INFO",
  "message":"writes info log",
  "time":"2020-12-31T23:59:59.999999999Z",
  "logging.googleapis.com/sourceLocation":{
    "file":"logger_test.go",
    "line":"57",
    "function":"github.com/devotedalpha/logz/internal/logger_test.TestLoggerWriteApplicationLog.func3"
  },
  "logging.googleapis.com/trace":"projects/test/traces/00000000000000000000000000000000",
  "logging.googleapis.com/spanId":"0000000000000000",
  "logging.googleapis.com/trace_sampled":false
}

Access log format

{
  "severity":"DEFAULT",
  "time":"2020-12-31T23:59:59.999999999Z",
  "logging.googleapis.com/trace":"projects/test/traces/a0d3eee13de6a4bbcf291eb444b94f28",
  "httpRequest":{
    "requestMethod":"GET",
    "requestUrl":"/test1",
    "requestSize":"0",
    "status":200,
    "responseSize":"333",
    "remoteIp":"192.0.2.1",
    "serverIp":"192.168.100.115",
    "latencyy":{
      "nanos":100,
      "seconds":0
    },
    "protocol":"HTTP/1.1"
  }
}

Documentation

Overview

Package logz provides the structured log with the OpenTelemetry.

Example:

ctx := r.Context() // r is *http.Request
logz.Infof(ctx, "info log. requestURL: %s", r.URL.String())

Example

package main

import (
	"log"
	"net/http"

	"github.com/devotedalpha/logz"
	"github.com/devotedalpha/logz/middleware"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		ctx := r.Context()

		// Writes info log
		logz.Infof(ctx, "writes %s log", "info")
	})

	logz.SetProjectID("your gcp project id")
	logz.InitTracer()
	// Sets the middleware
	h := middleware.NetHTTP("tracer name")(mux)

	log.Fatal(http.ListenAndServe(":8080", h))
}

Index

• func Access(ctx context.Context, r http.Request, statusCode, responseSize int, ...)
• func AccessLog(ctx context.Context, method, url, userAgent, remoteIP, protocol string, ...)
• func Criticalf(ctx context.Context, format string, a ...interface{})
• func Debugf(ctx context.Context, format string, a ...interface{})
• func Errorf(ctx context.Context, format string, a ...interface{})
• func Infof(ctx context.Context, format string, a ...interface{})
• func InitTracer()
• func SetConfig(cfg Config)
• func SetProjectID(projectID string)
• func StartCollectingSeverity(ctx context.Context) context.Context
• func Warningf(ctx context.Context, format string, a ...interface{})
• type Config

Examples

• Package
• SetConfig
• SetConfig (ChangeLogout)

Functions

func Access

func Access(ctx context.Context, r http.Request, statusCode, responseSize int, elapsed time.Duration)

Access writes access log to the stderr

func AccessLog

func AccessLog(ctx context.Context, method, url, userAgent, remoteIP, protocol string, statusCode, requestSize, responseSize int, elapsed time.Duration)

AccessLog writes access log to the stderr without http.Request

func Criticalf

func Criticalf(ctx context.Context, format string, a ...interface{})

Criticalf writes critical log to the stdout

func Debugf

func Debugf(ctx context.Context, format string, a ...interface{})

Debugf writes debug log to the stdout

func Errorf

func Errorf(ctx context.Context, format string, a ...interface{})

Errorf writes error log to the stdout

func Infof

func Infof(ctx context.Context, format string, a ...interface{})

Infof writes info log to the stdout

func InitTracer

func InitTracer()

InitTracer initializes OpenTelemetry tracer

func SetConfig

func SetConfig(cfg Config)

SetConfig sets config to the logger

Example

package main

import (
	"log"
	"net/http"

	"github.com/devotedalpha/logz"
	"github.com/devotedalpha/logz/middleware"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		ctx := r.Context()

		// Writes info log
		logz.Infof(ctx, "writes %s log", "info")
	})

	logz.SetConfig(logz.Config{
		ProjectID:      "your gcp project id",
		NeedsAccessLog: false, // Whether or not to write the access log
	})
	logz.InitTracer()
	// Sets the middleware
	h := middleware.NetHTTP("tracer name")(mux)

	log.Fatal(http.ListenAndServe(":8080", h))
}

Example (ChangeLogout)

package main

import (
	"log"
	"net/http"
	"os"

	"github.com/devotedalpha/logz"
	"github.com/devotedalpha/logz/middleware"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		ctx := r.Context()

		// Writes info log
		logz.Infof(ctx, "writes %s log", "info")
	})

	// Writes log on local file
	file, err := os.OpenFile("local.log", os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0777)
	if err != nil {
		panic(err)
	}
	logz.SetConfig(logz.Config{
		ProjectID:         "your gcp project id",
		NeedsAccessLog:    false,
		AccessLogOut:      file,
		ApplicationLogOut: file,
	})
	logz.InitTracer()
	// Sets the middleware
	h := middleware.NetHTTP("tracer name")(mux)

	log.Fatal(http.ListenAndServe(":8080", h))
}

func SetProjectID

func SetProjectID(projectID string)

SetProjectID sets gcp project id to the logger

func StartCollectingSeverity

func StartCollectingSeverity(ctx context.Context) context.Context

StartCollectingSeverity starts collectiong severity

func Warningf

func Warningf(ctx context.Context, format string, a ...interface{})

Warningf writes warning log to the stdout

Types

type Config

type Config struct {
	// GCP Project ID
	ProjectID string
	// CallerDepth is the number of stack frames to ascend
	CallerSkip int
	// Whether or not to write the access log
	NeedsAccessLog bool
	// Output for application log
	ApplicationLogOut io.Writer
	// Output for access log
	AccessLogOut io.Writer
}

Config is configurations for logz