Go
Structured logs from your Go services, with a log/slog handler. Standard library only.
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/lyrelogStart
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 itA 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
categorystring attribute sets the area (and isn't sent as an attribute); without one the handler'sCategoryis used. - Levels:
Debug-4and below istrace,Debugisdebug,Infoisinfo, betweenInfoandWarnisnotice,Warniswarning,Erroriserror,Error+4and above iscritical. SlogOptions.Leveladds a minimum on top of the client's;AddSourceadds asourceattribute with the caller's function, file and line. Build withgo build -trimpathso 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
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 stopFlush sends everything queued before the call and waits for it or for ctx. It returns:
nilwhen everything reached the server;ctx.Err()if the context ended first;ErrUnauthorizedafter a401or403(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-Afterthe server asked for,Flushreturns this at once and sends nothing; ErrClosedafterClose.
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
| Field | Default | Meaning |
|---|---|---|
Endpoint | https://ingest.lyrelog.com | The base URL; a pasted /v1/... path is removed. Plain http:// only for localhost |
APIKey | required | The project's server key (lyr_srv_...), or an ingest key |
Environment | $LYRELOG_ENVIRONMENT, else production | Any valid name |
Platform | go | api, worker... |
Release | the module version | Sent as resource.app_version |
AppID | the module path | Sent as resource.app_id |
MinimumLevel | LevelDebug | Events below it are dropped before queueing |
FlushInterval | 5 s | How often the background goroutine sends |
MaxQueue | 10,000 | Oldest dropped beyond it, counted in Stats().Dropped |
MaxQueueBytes | 16 MiB | The same cap, in bytes |
CloseTimeout | 5 s | How long Close waits for the last flush |
HTTPClient | 30 s timeout | The client that sends batches. Redirects are never followed, even with your own client |
ErrorLog | stderr, once | Receives 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,apikeyand 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.RedactKeysreplaces 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 toMaxQueue. The client logs one warning toErrorLog(or stderr) and says nothing more until a batch is accepted. - Context:
os_nameisruntime.GOOS,app_buildthe 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.statusishttp_status), errors, times, durations andStringers become strings, structs their JSON form, NaNnull. 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
Configor a*Clientwithfmthides the API key.