usage.md

title	expires_at	tags
Usage	never	diego-release lager

Usage

Instantiate a logger with the name of your component.

import (
  "code.cloudfoundry.org/lager/v3"
)

logger := lager.NewLogger("my-app")

Lager and log/slog

Lager was written long before Go 1.21 introduced structured logging in the standard library. There are some wrapper functions for interoperability between Lager and slog, which are only available when using Go 1.21 and higher.

Lager can be used as an slog.Handler using the NewHandler() function:

func codeThatAcceptsSlog(l *slog.Logger) { ... }

lagerLogger := lager.NewLogger("my-lager-logger")

codeThatAcceptsSlog(slog.New(lager.NewHandler(lagerLogger)))

An slog.Logger can be used as a Lager Sink using the NewSlogSink() function:

var *slog.Logger l = codeThatReturnsSlog()

lagerLogger := lager.NewLogger("my-lager-logger")

lagerLogger.RegisterSink(lager.NewSlogSink(l))

Sinks

Lager can write logs to a variety of destinations. You can specify the destinations using Lager sinks:

To write to an arbitrary Writer object:

logger.RegisterSink(lager.NewWriterSink(myWriter, lager.INFO))

Emitting logs

Lager supports the usual level-based logging, with an optional argument for arbitrary key-value data.

logger.Info("doing-stuff", lager.Data{
  "informative": true,
})

output:

{ "source": "my-app", "message": "doing-stuff", "data": { "informative": true }, "timestamp": 1232345, "log_level": 1 }

Error messages also take an Error object:

logger.Error("failed-to-do-stuff", errors.New("Something went wrong"))

output:

{ "source": "my-app", "message": "failed-to-do-stuff", "data": { "error": "Something went wrong" }, "timestamp": 1232345, "log_level": 1 }

Sessions

You can avoid repetition of contextual data using 'Sessions':

contextualLogger := logger.Session("my-task", lager.Data{
  "request-id": 5,
})

contextualLogger.Info("my-action")

output:

{ "source": "my-app", "message": "my-task.my-action", "data": { "request-id": 5 }, "timestamp": 1232345, "log_level": 1 }