Early accessBy invitation, and the SDKs aren't published yet.Ask for an invitation
Skip to Content
Docs

Go

Structured logs from your Go services, with a log/slog handler. Standard library only.

Servers, with a slog handler

The module is go.lyrelog.com/lyrelog. It needs Go 1.24 or later and has no dependencies.

Internal preview: this package isn't published yet. Until it is, go get go.lyrelog.com/lyrelog fails: the repository is private and has no release yet.

Install

go get go.lyrelog.com/lyrelog

Start

import "go.lyrelog.com/lyrelog"

client, err := lyrelog.New(lyrelog.Config{
	APIKey:   "lyr_srv_...", // a server key, or read it from your own config
	Platform: "api",
})
if err != nil {
	log.Fatal(err) // only for a bad config: logging itself never fails
}
defer client.Close() // sends what is left (waits at most 5 s)

Use a server key, lyr_srv_..., from the project's API keys page (Send events from a server). It is a secret: keep it in your server's environment, never in an app or a web page. Its events are verified, and one address has no daily share of the month. An ingest key, lyr_ing_..., works too, but its events aren't verified.

Only APIKey is required: without it New returns an error and a nil client. A nil *Client does nothing, so code can log before (or without) one. Endpoint defaults to https://ingest.lyrelog.com; it is the base URL, and a pasted /v1/events:batch path is removed.

log.Fatal and os.Exit skip deferred calls, so defer client.Close() never runs after them. In main, return an exit code from a function that does the work:

func main() { os.Exit(run()) }

func run() int {
	client, err := lyrelog.New(lyrelog.Config{APIKey: os.Getenv("LYRELOG_KEY")})
	if err != nil {
		fmt.Fprintln(os.Stderr, err) // client is nil and does nothing: carry on without it
	}
	defer client.Close() // runs before os.Exit
	// ...
	return 0
}

In a serverless function (AWS Lambda), call client.Flush(ctx) before the handler returns: the runtime may freeze the process before the next send.

Log events

One method per level: Trace, Debug, Info, Notice, Warning, Error, Critical, or Log(level, message, ...). Details are options: lyrelog.Category, lyrelog.Attrs, lyrelog.Payload and lyrelog.User.

client.Info("checkout_done", lyrelog.Attrs{"plan": "pro", "latency_ms": 412})
client.Error("payment_failed",
	lyrelog.Category("billing"),
	lyrelog.Attrs{"code": "card_declined"},
	lyrelog.Payload(map[string]any{"response": body}),
)

Attributes can be strings, numbers, booleans, nil, string slices and nested maps (4 levels). Names with dots are rewritten with _. Several Attrs options merge, a later key wins. A Payload is encoded with encoding/json: pass json.RawMessage for bytes that already are JSON (a plain []byte arrives as a base64 string).

Loggers for each area

billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})

Users

client.SetUser("u_123") // attached to every following event
client.SetUser("")      // clear it

A server handles many people at once: set the user on each event with lyrelog.User(id), which replaces the one from SetUser for that event.

The slog handler

Send log/slog records to Lyrelog:

logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")
  • The record's message is the event's message, its time the event's time; attributes and groups become nested attributes.
  • A top-level category string attribute sets the area (and isn't sent as an attribute); without one the handler's Category is used.
  • Levels: Debug-4 and below is trace, Debug is debug, Info is info, between Info and Warn is notice, Warn is warning, Error is error, Error+4 and above is critical.
  • SlogOptions.Level adds a minimum on top of the client's; AddSource adds a source attribute with the caller's function, file and line. Build with go build -trimpath so the file holds module paths rather than your build machine's directories.

To keep printing to the terminal as well, send each record to both handlers. On Go 1.26 or later, slog.NewMultiHandler does it:

logger := slog.New(slog.NewMultiHandler(
	slog.NewTextHandler(os.Stderr, nil),
	lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)

A net/http middleware

There is no built-in middleware. This one records every request as http_request_served in the http area, at info, warning for a 4xx and error for a 5xx, with the route pattern rather than the path, so ids don't explode the cardinality:

func logRequests(client *lyrelog.Client, next http.Handler) http.Handler {
	httpLog := client.Logger("http")
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(recorder, r)
		level := lyrelog.LevelInfo
		switch {
		case recorder.status >= 500:
			level = lyrelog.LevelError
		case recorder.status >= 400:
			level = lyrelog.LevelWarning
		}
		httpLog.Log(level, "http_request_served", lyrelog.Attrs{
			"method":      r.Method,
			"route":       r.Pattern, // set by http.ServeMux (Go 1.23+), e.g. "GET /users/{id}"
			"status":      recorder.status,
			"duration_ms": time.Since(start).Milliseconds(),
		})
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (s *statusRecorder) WriteHeader(code int) {
	s.status = code
	s.ResponseWriter.WriteHeader(code)
}

// Unwrap lets http.ResponseController reach the original writer (Flush, deadlines).
func (s *statusRecorder) Unwrap() http.ResponseWriter { return s.ResponseWriter }

// http.ListenAndServe(":8080", logRequests(client, mux))

r.Pattern is empty for a request no route matched.

Errors

if err := charge(ctx, order); err != nil {
	client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}

The event is exception, level error, with error_type and error_message in the attributes and, in the payload, the error's chain (each wrapped error) and the stack. A nil error logs nothing. Logger.CaptureError does the same with the logger's category. The level is always error: for another one, log the error yourself with Log.

Panics

The SDK doesn't recover panics. net/http recovers a handler's panic and only prints it, so record it in a middleware, outside the one above:

func recoverPanics(client *lyrelog.Client, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			v := recover()
			if v == nil {
				return
			}
			if v == http.ErrAbortHandler {
				panic(v)
			}
			err, ok := v.(error)
			if !ok {
				err = fmt.Errorf("panic: %v", v)
			}
			client.CaptureError(err, lyrelog.Category("http"),
				lyrelog.Attrs{"handled": false, "mechanism": "panic", "route": r.Pattern})
			http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
		}()
		next.ServeHTTP(w, r)
	})
}

// http.ListenAndServe(":8080", recoverPanics(client, logRequests(client, mux)))

The stack in the payload is taken where the panic was recovered, so it still shows the frames that panicked. A panic in a goroutine of your own crashes the program before anything is sent: recover it in that goroutine the same way.

Environments and platform

Environment defaults to the LYRELOG_ENVIRONMENT environment variable (lowercased), else production. Platform defaults to go. Set either in the config:

client, err := lyrelog.New(lyrelog.Config{
	APIKey:      "lyr_srv_...",
	Environment: "staging",
	Platform:    "worker",
})

Both must be lowercase letters, digits, - and _, up to 32, starting with a letter or digit. An invalid Config.Environment or Config.Platform makes New return an error; an invalid $LYRELOG_ENVIRONMENT is reported to ErrorLog and replaced by production, so a typo in a deploy never stops a service. Release defaults to the main module's version from the build info, and AppID to the main module's path.

Consent is for apps that run on someone's device. A server SDK sends what it is given.

Flush and stop

err := client.Flush(ctx) // send what's queued now
client.Close()           // flush (up to CloseTimeout) and stop

Flush sends everything queued before the call and waits for it or for ctx. It returns:

  • nil when everything reached the server;
  • ctx.Err() if the context ended first;
  • ErrUnauthorized after a 401 or 403 (the client stops sending until the process restarts and keeps its queue);
  • an error saying a batch was refused and dropped (the rest was still sent);
  • an error saying delivery failed and will be retried, with the events kept. Inside a Retry-After the server asked for, Flush returns this at once and sends nothing;
  • ErrClosed after Close.

Close waits at most CloseTimeout for the last flush and returns the same values; events still unsent then are dropped and counted in Stats().Dropped. After Close, log calls do nothing.

client.Stats() returns Queued (waiting, including a batch being retried), Sent (accepted by the server), Rejected (lines the server refused, never resent) and Dropped (by the client: queue overflow, a refused batch, or left at Close).

In development and tests

Without an APIKey, New returns an error and a nil client, and a nil client does nothing: the same code runs in tests and on a laptop without a key, as in the run example above. The slog handler over a nil client drops every record.

To see what a test logs, pass an HTTPClient whose Transport records the requests, or point Endpoint at an httptest.Server (plain http:// is allowed for loopback addresses).

Verified events

A verified event is one that can't have been sent by someone who copied the public ingest key out of an app or a web page. What that proves, and what it doesn't, is on Verified events.

Send with a server key, lyr_srv_.... Every event it sends is verified (verified_by is server) and doesn't count toward the daily share of one address. An owner makes it on the project's API keys page, Send events from a server, after a recent sign-in (within 10 minutes), and it is shown once. It is a secret: keep it out of the repository and read it from the server's environment or secret store.

client, err := lyrelog.New(lyrelog.Config{
	APIKey: os.Getenv("LYRELOG_KEY"), // lyr_srv_..., set in the server's environment
})

To check, open the explorer: in Filter, pick Verified by and Server key (the other values are App Attest and Not verified). An opened event says it under Context, in its Sender line: Verified, server key, or Not verified, public key.

Events sent with an ingest key, lyr_ing_..., or a full-access key, lyr_adm_..., arrive unverified: anyone holding a public key could have sent the same, and they count toward the daily share. A verified event proves who sent it, not that what it says is true.

See Verified events for who verifies what and the daily share.

Configuration

FieldDefaultMeaning
Endpointhttps://ingest.lyrelog.comThe base URL; a pasted /v1/... path is removed. Plain http:// only for localhost
APIKeyrequiredThe project's server key (lyr_srv_...), or an ingest key
Environment$LYRELOG_ENVIRONMENT, else productionAny valid name
Platformgoapi, worker...
Releasethe module versionSent as resource.app_version
AppIDthe module pathSent as resource.app_id
MinimumLevelLevelDebugEvents below it are dropped before queueing
FlushInterval5 sHow often the background goroutine sends
MaxQueue10,000Oldest dropped beyond it, counted in Stats().Dropped
MaxQueueBytes16 MiBThe same cap, in bytes
CloseTimeout5 sHow long Close waits for the last flush
HTTPClient30 s timeoutThe client that sends batches. Redirects are never followed, even with your own client
ErrorLogstderr, onceReceives the SDK's own diagnostics, each starting with lyrelog: . Without it, only the first refused key or dropped batch (once) and the quota warning are printed to stderr. Don't point it at a logger that feeds this client

Delivery and limits

  • One background goroutine batches up to 500 events or 512 KiB, gzipped; a full batch is sent right away. Safe for concurrent use.
  • Retries with full jitter (1 s doubling to 5 min), honoring Retry-After (seconds or a date), resending the same bytes. Any other 4xx drops the batch; a 3xx drops it and logs a warning.
  • Values under keys whose name is or ends with authorization, cookie, password, token, secret, apikey and the rest of the shared list become "[redacted]" before queueing: in attributes and the payload, at any depth (maps, structs by their JSON names, slices, http.Header), before anything is cut. Config.RedactKeys replaces the list and an empty, non-nil slice turns it off; to add to it, RedactKeys: append(lyrelog.DefaultRedactKeys(), "pin").
  • When a Free organization has used its month's events, the server answers 429. The events stay in memory and go out once the server takes them again, up to MaxQueue. The client logs one warning to ErrorLog (or stderr) and says nothing more until a batch is accepted.
  • Context: os_name is runtime.GOOS, app_build the VCS revision when the binary has one, and the install and session ids are per process.
  • Limits are applied before queueing: past 200 leaves attributes are dropped and counted in lyrelog_dropped_attrs, dots in names become _ (http.status is http_status), errors, times, durations and Stringers become strings, structs their JSON form, NaN null. A payload over 64 KiB becomes {"lyrelog_truncated": true, "bytes": N, "preview": "..."} with its first KiB. One event's attributes are capped at 256 KiB encoded, and an event that can't fit in a 512 KiB batch is dropped and counted.
  • Printing a Config or a *Client with fmt hides the API key.