logger

package
v0.135.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2023 License: Apache-2.0 Imports: 15 Imported by: 0

README

package logger

Package logger provides tooling for structured logging. With logger, you can use context to add logging details to your call stack.

How to use

package main

import (
	"context"

	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()

	// You can add details to the context; thus, every logging call using this context will inherit the details.
	ctx = logger.ContextWith(ctx, logger.Fields{
		"foo": "bar",
		"baz": "qux",
	})

	// You can use your own Logger instance or the logger.Default logger instance if you plan to log to the STDOUT. 
	logger.Info(ctx, "foo", logger.Fields{
		"userID":    42,
		"accountID": 24,
	})
}

example output when snake case key format is defined (default):

{
  "account_id": 24,
  "baz": "qux",
  "foo": "bar",
  "level": "info",
  "message": "foo",
  "timestamp": "2023-04-02T16:00:00+02:00",
  "user_id": 42
}

example output when camel key format is defined:

{
  "accountID": 24,
  "baz": "qux",
  "foo": "bar",
  "level": "info",
  "message": "foo",
  "timestamp": "2023-04-02T16:00:00+02:00",
  "userID": 42
}

How to configure:

logger.Logger can be configured through its struct fields; please see the documentation for more details. To configure the default logger, simply configure it from your main.

package main

import "github.com/adamluzsi/frameless/pkg/logger"

func main() {
    logger.Default.MessageKey = "msg"
    logger.Default.TimestampKey = "ts"
}

Key string case style consistency in your logs

Using the logger package can help you maintain historical consistency in your logging key style and avoid mixed string case styles. This is particularly useful since many log collecting systems rely on an append-only strategy, and any inconsistency could potentially cause issues with your alerting scripts that rely on certain keys. So, by using the logger package, you can ensure that your logging is clean and consistent, making it easier to manage and troubleshoot any issues that may arise.

The default key format is snake_case, but you can change it easily by supplying a formetter in the KeyFormatter Logger field.

package main

import (
	"github.com/adamluzsi/frameless/pkg/logger"
	"github.com/adamluzsi/frameless/pkg/stringcase"
)

func main() {
	logger.Default.KeyFormatter = stringcase.ToKebab
}

Security concerns

It is crucial to make conscious decisions about what we log from a security standpoint because logging too much information can potentially expose sensitive data about users. On the other hand, by logging what is necessary and relevant for operations, we can avoid security and compliance issues. Following this practice can reduce the attack surface of our system and limit the potential impact of a security breach. Additionally, logging too much information can make detecting and responding to security incidents more difficult, as the noise of unnecessary data can obscure the signal of actual threats.

The logger package has a safety mechanism to prevent exposure of sensitive data; it requires you to register any DTO or Entity struct type with the logging package before you can use it as a logging field.

package mydomain

import "github.com/adamluzsi/frameless/pkg/logger"

type MyEntity struct {
	ID               string
	NonSensitiveData string
	SensitiveData    string
}

var _ = logger.RegisterFieldType(func(ent MyEntity) logger.LoggingDetail {
	return logger.Fields{
		"id":   ent.ID,
		"data": ent.NonSensitiveData,
	}
})

Documentation

Overview

Package logger provides tooling for structured logging. With logger, you can use context to add logging details to your call stack.

Example (WithDetails) 
package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Info(ctx, "foo", logger.Fields{
		"userID":    42,
		"accountID": 24,
	})
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContextWith added in v0.135.0 

func ContextWith(ctx context.Context, lds ...LoggingDetail) context.Context
Example 
package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()

	ctx = logger.ContextWith(ctx, logger.Fields{
		"foo": "bar",
		"baz": "qux",
	})

	logger.Info(ctx, "message") // will have details from the context
}

Output:

func Debug 

func Debug(ctx context.Context, msg string, ds ...LoggingDetail)
Example 
package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Debug(ctx, "foo")
}

Output:

func Error 

func Error(ctx context.Context, msg string, ds ...LoggingDetail)
Example 
package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Error(ctx, "foo")
}

Output:

func Fatal 

func Fatal(ctx context.Context, msg string, ds ...LoggingDetail)
Example 
package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Fatal(ctx, "foo")
}

Output:

func Info 

func Info(ctx context.Context, msg string, ds ...LoggingDetail)
Example 
package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Info(ctx, "foo")
}

Output:

func RegisterFieldType added in v0.135.0 

func RegisterFieldType[T any](mapping func(T) LoggingDetail) any
Example 
package main

import (
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	type MyEntity struct {
		ID               string
		NonSensitiveData string
		SensitiveData    string
	}

	// at package level
	var _ = logger.RegisterFieldType(func(ent MyEntity) logger.LoggingDetail {
		return logger.Fields{
			"id":   ent.ID,
			"data": ent.NonSensitiveData,
		}
	})
}

Output:

func Stub 

func Stub(tb testingTB) *bytes.Buffer

Stub the logger.Default and return the buffer where the logging output will be recorded. Stub will restore the logger.Default after the test.

Example 
package main

import (
	"github.com/adamluzsi/frameless/pkg/logger"
	"strings"
	"testing"
)

func main() {
	var tb testing.TB
	buf := logger.Stub(tb) // stub will clean up after itself when the test is finished
	logger.Info(nil, "foo")
	strings.Contains(buf.String(), "foo") // true
}

Output:

func Warn 

func Warn(ctx context.Context, msg string, ds ...LoggingDetail)
Example 
package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Warn(ctx, "foo")
}

Output:

Types

type Details 

type Details = Fields

Details

DEPRECATED: use logging.Fields instead

type Fields added in v0.135.1 

type Fields map[string]any
Example 
package main

import (
	"context"

	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	logger.Error(context.Background(), "msg", logger.Fields{
		"key1": "value",
		"key2": "value",
	})
}

Output:

type Logger 

type Logger struct {
	Out io.Writer

	Separator string

	MessageKey   string
	LevelKey     string
	TimestampKey string

	// MarshalFunc is used to serialise the logging message event.
	// When nil it defaults to JSON format.
	MarshalFunc func(any) ([]byte, error)
	// KeyFormatter will be used to format the logging field keys
	KeyFormatter func(string) string
	// contains filtered or unexported fields
}
var Default Logger

func (*Logger) Debug 

func (l *Logger) Debug(ctx context.Context, msg string, ds ...LoggingDetail)

func (*Logger) Error 

func (l *Logger) Error(ctx context.Context, msg string, ds ...LoggingDetail)

func (*Logger) Fatal 

func (l *Logger) Fatal(ctx context.Context, msg string, ds ...LoggingDetail)

func (*Logger) Field added in v0.135.0 

func (l *Logger) Field(key string, value any) LoggingDetail

func (*Logger) Info 

func (l *Logger) Info(ctx context.Context, msg string, ds ...LoggingDetail)

func (*Logger) Warn 

func (l *Logger) Warn(ctx context.Context, msg string, ds ...LoggingDetail)

type LoggingDetail added in v0.135.0 

type LoggingDetail interface {
	// contains filtered or unexported methods
}

func ErrField added in v0.135.0 

func ErrField(err error) LoggingDetail
Example 
package main

import (
	"context"
	"errors"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	err := errors.New("boom")

	logger.Error(ctx, "task failed successfully", logger.ErrField(err))
}

Output:

func Field added in v0.135.0 

func Field(key string, value any) LoggingDetail
Example 
package main

import (
	"context"

	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	logger.Error(context.Background(), "msg",
		logger.Field("key1", "value"),
		logger.Field("key2", "value"))
}

Output:

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.