Go
Strukturierte Logs aus deinen Go-Services, mit einem log/slog-Handler. Nur die Standardbibliothek.
Das Modul ist go.lyrelog.com/lyrelog. Es braucht Go 1.24 oder neuer und
hat keine Abhängigkeiten.
Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin schlägt go get go.lyrelog.com/lyrelog
fehl: Das Repository ist privat und hat noch kein Release.
Installation
go get go.lyrelog.com/lyrelogStarten
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)Verwende einen Server-Schlüssel, lyr_srv_..., von der Seite API keys des Projekts (Send
events from a server). Er ist geheim: Bewahre ihn in der Umgebung deines Servers auf,
nie in einer App oder einer Webseite. Seine Events sind verifiziert,
und das Tageslimit für die Adresse eines einzelnen Absenders gilt für sie nicht. Ein Ingest-Schlüssel,
lyr_ing_..., funktioniert auch, aber seine Events sind nicht verifiziert.
Nur APIKey ist erforderlich: Ohne ihn gibt New einen Fehler und einen nil-Client zurück.
Ein nil-*Client tut nichts, sodass Code schon vor einem Client (oder ganz ohne) loggen kann.
Endpoint ist standardmäßig https://ingest.lyrelog.com; das ist die Basis-URL, und ein
eingefügter Pfad /v1/events:batch wird entfernt.
log.Fatal und os.Exit überspringen Deferred-Aufrufe, defer client.Close() läuft danach also
nie. Gib in main einen Exit-Code aus einer Funktion zurück, die die eigentliche Arbeit macht:
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 einer Serverless-Funktion (AWS Lambda) rufst du client.Flush(ctx) auf, bevor der Handler
zurückkehrt: Die Laufzeitumgebung kann den Prozess vor dem nächsten Senden einfrieren.
Events loggen
Eine Methode pro Level: Trace, Debug, Info, Notice, Warning, Error, Critical oder
Log(level, message, ...). Details sind Optionen: lyrelog.Category, lyrelog.Attrs,
lyrelog.Payload und 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}),
)Attribute können Strings, Zahlen, Booleans, nil, String-Slices und verschachtelte Maps (4 Ebenen)
sein. Namen mit Punkten werden mit _ umgeschrieben. Mehrere Attrs-Optionen werden
zusammengeführt, ein späterer Schlüssel gewinnt. Ein Payload wird mit encoding/json kodiert:
Übergib json.RawMessage für Bytes, die schon JSON sind (ein einfaches []byte kommt als
Base64-String an).
Logger für jeden Bereich
billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})Nutzer
client.SetUser("u_123") // attached to every following event
client.SetUser("") // clear itEin Server bedient viele Personen gleichzeitig: Setz den Nutzer bei jedem Event mit
lyrelog.User(id), das für dieses Event den Nutzer aus SetUser ersetzt.
Der slog-Handler
Schick log/slog-Records an Lyrelog:
logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")- Die Nachricht des Records wird zur Nachricht des Events, seine Zeit zur Zeit des Events; Attribute und Gruppen werden zu verschachtelten Attributen.
- Ein String-Attribut
categoryauf oberster Ebene setzt den Bereich (und wird nicht als Attribut gesendet); ohne eines wird dieCategorydes Handlers verwendet. - Levels:
Debug-4und darunter isttrace,Debugistdebug,Infoistinfo, zwischenInfoundWarnistnotice,Warnistwarning,Erroristerror,Error+4und darüber istcritical. SlogOptions.Levellegt zusätzlich zu dem des Clients ein Minimum fest;AddSourcefügt ein Attributsourcemit Funktion, Datei und Zeile des Aufrufers hinzu. Bau mitgo build -trimpath, damit die Datei Modulpfade enthält statt der Verzeichnisse deines Build-Rechners.
Wenn du weiterhin auch ins Terminal schreiben willst, schick jeden Record an beide Handler. Ab Go
1.26 erledigt das slog.NewMultiHandler:
logger := slog.New(slog.NewMultiHandler(
slog.NewTextHandler(os.Stderr, nil),
lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)Eine net/http-Middleware
Es gibt keine eingebaute Middleware. Diese hier zeichnet jeden Request als http_request_served
im Bereich http auf, mit info, bei einem 4xx mit warning und bei einem 5xx mit error, mit dem
Routen-Pattern statt des Pfads, damit IDs die Kardinalität nicht sprengen:
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 ist leer bei einem Request, auf den keine Route gepasst hat.
Fehler
if err := charge(ctx, order); err != nil {
client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}Das Event ist exception, Level error, mit error_type und error_message in den Attributen
und, im Payload, der Fehlerkette (jeder gewrappte Fehler) und dem Stack. Ein nil-Fehler loggt
nichts. Logger.CaptureError macht dasselbe mit der Kategorie des Loggers. Das Level ist immer
error: Für ein anderes loggst du den Fehler selbst mit Log.
Panics
Das SDK fängt keine Panics ab. net/http fängt die Panic eines Handlers ab und gibt sie nur aus,
zeichne sie also in einer Middleware auf, die außen um die obige liegt:
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)))Der Stack im Payload wird dort aufgenommen, wo die Panic abgefangen wurde, er zeigt also weiterhin die Frames, die die Panic ausgelöst haben. Eine Panic in einer eigenen Goroutine bringt das Programm zum Absturz, bevor irgendetwas gesendet wird: Fang sie in dieser Goroutine auf dieselbe Weise ab.
Umgebungen und Plattform
Environment ist standardmäßig die Umgebungsvariable LYRELOG_ENVIRONMENT (kleingeschrieben),
sonst production. Platform ist standardmäßig go. Beides kannst du in der Konfiguration setzen:
client, err := lyrelog.New(lyrelog.Config{
APIKey: "lyr_srv_...",
Environment: "staging",
Platform: "worker",
})Beide müssen aus Kleinbuchstaben, Ziffern, - und _ bestehen, bis zu 32 Zeichen, und mit einem
Buchstaben oder einer Ziffer beginnen. Ein ungültiges Config.Environment oder Config.Platform
lässt New einen Fehler zurückgeben; ein ungültiges $LYRELOG_ENVIRONMENT wird an ErrorLog
gemeldet und durch production ersetzt, damit ein Tippfehler in einem Deployment nie einen
Service stoppt.
Release ist standardmäßig die Version des Hauptmoduls aus den Build-Infos, und AppID der Pfad
des Hauptmoduls.
Einwilligung
Einwilligung betrifft Apps, die auf dem Gerät einer Person laufen. Ein Server-SDK sendet, was es bekommt.
Flush und Stopp
err := client.Flush(ctx) // send what's queued now
client.Close() // flush (up to CloseTimeout) and stopFlush sendet alles, was vor dem Aufruf in der Warteschlange lag, und wartet darauf oder auf
ctx. Es gibt zurück:
nil, wenn alles beim Server angekommen ist;ctx.Err(), wenn der Context zuerst endete;ErrUnauthorizednach einem401oder403(der Client sendet bis zum Neustart des Prozesses nicht mehr und behält seine Warteschlange);- einen Fehler, der besagt, dass ein Batch abgelehnt und verworfen wurde (der Rest wurde trotzdem gesendet);
- einen Fehler, der besagt, dass die Zustellung fehlgeschlagen ist und wiederholt wird, wobei die
Events behalten werden. Innerhalb eines
Retry-After, das der Server verlangt hat, gibtFlushdiesen sofort zurück und sendet nichts; ErrClosednachClose.
Close wartet höchstens CloseTimeout auf den letzten Flush und gibt dieselben Werte zurück;
Events, die dann noch nicht gesendet sind, werden verworfen und in Stats().Dropped gezählt. Nach
Close tun Log-Aufrufe nichts mehr.
client.Stats() gibt Queued (wartend, einschließlich eines Batches, der gerade wiederholt
wird), Sent (vom Server angenommen), Rejected (Zeilen, die der Server abgelehnt hat, nie
erneut gesendet) und Dropped (vom Client verworfen: Überlauf der Warteschlange, ein abgelehnter
Batch oder bei Close übrig) zurück.
In Entwicklung und Tests
Ohne APIKey gibt New einen Fehler und einen nil-Client zurück, und ein nil-Client tut
nichts: Derselbe Code läuft in Tests und auf einem Laptop ohne Schlüssel, wie im Beispiel mit
run oben. Der slog-Handler über einem nil-Client verwirft jeden Record.
Um zu sehen, was ein Test loggt, übergib einen HTTPClient, dessen Transport die Requests
aufzeichnet, oder richte Endpoint auf einen httptest.Server (einfaches http:// ist für
Loopback-Adressen erlaubt).
Verifizierte Events
Ein verifiziertes Event kann nicht von jemandem gesendet worden sein, der den öffentlichen Ingest-Schlüssel aus einer App oder einer Webseite kopiert hat. Was das beweist und was nicht, steht unter Verifizierte Events.
Sende mit einem Server-Schlüssel, lyr_srv_.... Jedes Event, das er sendet, ist verifiziert
(verified_by ist server) und zählt nicht zum
Tagesanteil einer Adresse. Ein Inhaber
erstellt ihn auf der Seite API keys des Projekts unter Send events from a server, nach einer
frischen Anmeldung (innerhalb von 10 Minuten), und er wird nur einmal angezeigt. Er ist
geheim: Check ihn nicht ins Repository ein, sondern lies ihn aus der Umgebung oder dem
Secret-Store des Servers.
client, err := lyrelog.New(lyrelog.Config{
APIKey: os.Getenv("LYRELOG_KEY"), // lyr_srv_..., set in the server's environment
})Zur Kontrolle öffnest du den Explorer: Wähl unter Filter erst Verified by und dann Server key (die anderen Werte sind App Attest und Not verified). Ein geöffnetes Event zeigt es unter Context in seiner Zeile Sender: Verified, server key oder Not verified, public key.
Events, die mit einem Ingest-Schlüssel, lyr_ing_..., oder einem Vollzugriffs-Schlüssel,
lyr_adm_..., gesendet werden, kommen unverifiziert an: Jeder mit einem öffentlichen Schlüssel
hätte dasselbe senden können, und sie zählen zum Tagesanteil. Ein verifiziertes Event beweist,
wer es gesendet hat, nicht, dass sein Inhalt stimmt.
Unter Verifizierte Events steht, wer was verifiziert und wie der Tagesanteil funktioniert.
Konfiguration
| Feld | Standard | Bedeutung |
|---|---|---|
Endpoint | https://ingest.lyrelog.com | Die Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Einfaches http:// nur für localhost |
APIKey | erforderlich | Der Server-Schlüssel des Projekts (lyr_srv_...) oder ein Ingest-Schlüssel |
Environment | $LYRELOG_ENVIRONMENT, sonst production | Jeder gültige Name |
Platform | go | api, worker... |
Release | die Modulversion | Wird als resource.app_version gesendet |
AppID | der Modulpfad | Wird als resource.app_id gesendet |
MinimumLevel | LevelDebug | Events darunter werden verworfen, bevor sie in die Warteschlange kommen |
FlushInterval | 5 s | Wie oft die Hintergrund-Goroutine sendet |
MaxQueue | 10.000 | Darüber hinaus fallen die ältesten weg, gezählt in Stats().Dropped |
MaxQueueBytes | 16 MiB | Dieselbe Grenze, in Bytes |
CloseTimeout | 5 s | Wie lange Close auf den letzten Flush wartet |
HTTPClient | 30 s Timeout | Der Client, der die Batches sendet. Weiterleitungen werden nie verfolgt, auch nicht mit deinem eigenen Client |
ErrorLog | stderr, einmal | Empfängt die eigenen Diagnosemeldungen des SDK, jede beginnt mit lyrelog: . Ohne ihn werden nur der erste abgelehnte Schlüssel oder verworfene Batch und die Kontingentwarnung auf stderr ausgegeben. Richte ihn nicht auf einen Logger, der in diesen Client schreibt |
Zustellung und Limits
- Eine Hintergrund-Goroutine bündelt bis zu 500 Events oder 512 KiB, mit gzip komprimiert; ein voller Batch wird sofort gesendet. Sicher für nebenläufige Nutzung.
- Wiederholungen mit Full Jitter (1 s, verdoppelt bis 5 min), unter Beachtung von
Retry-After(Sekunden oder ein Datum), wobei dieselben Bytes erneut gesendet werden. Jeder andere 4xx-Status verwirft den Batch; ein 3xx-Status verwirft ihn und loggt eine Warnung. - Werte unter Schlüsseln, deren Name
authorization,cookie,password,token,secret,apikeyoder einer der übrigen Einträge der gemeinsamen Liste ist oder darauf endet, werden vor dem Einreihen zu"[redacted]": in Attributen und im Payload, in jeder Tiefe (Maps, Structs über ihre JSON-Namen, Slices,http.Header), bevor irgendetwas gekürzt wird.Config.RedactKeysersetzt die Liste, und ein leeres Slice, das nicht nil ist, schaltet es ab; zum Ergänzen nimmst duRedactKeys: append(lyrelog.DefaultRedactKeys(), "pin"). - Wenn eine Free-Organisation die Events ihres Monats aufgebraucht hat, antwortet der Server mit
429. Die Events bleiben im Speicher und gehen raus, sobald der Server sie wieder annimmt, bis zuMaxQueue. Der Client loggt eine Warnung anErrorLog(oder stderr) und schweigt dann, bis ein Batch angenommen wurde. - Kontext:
os_nameistruntime.GOOS,app_builddie VCS-Revision, wenn das Binary eine hat, und Installations- und Session-ID gelten pro Prozess. - Limits werden vor dem Einreihen angewendet: Attribute jenseits von 200 Blattwerten
(verschachtelte Werte einzeln gezählt) werden verworfen und in
lyrelog_dropped_attrsgezählt, Punkte in Namen werden zu_(http.statuswirdhttp_status), Fehler, Zeitpunkte, Dauern undStringerwerden zu Strings, Structs zu ihrer JSON-Form, NaN zunull. Ein Payload über 64 KiB wird zu{"lyrelog_truncated": true, "bytes": N, "preview": "..."}mit seinem ersten KiB. Die Attribute eines Events sind kodiert auf 256 KiB begrenzt, und ein Event, das nicht in einen Batch von 512 KiB passt, wird verworfen und gezählt. - Wenn du eine
Configoder einen*Clientmitfmtausgibst, wird der API-Schlüssel verborgen.