Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

Go

Strukturierte Logs aus deinen Go-Services, mit einem log/slog-Handler. Nur die Standardbibliothek.

Server, mit einem slog-Handler

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/lyrelog

Starten

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 it

Ein 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 category auf oberster Ebene setzt den Bereich (und wird nicht als Attribut gesendet); ohne eines wird die Category des Handlers verwendet.
  • Levels: Debug-4 und darunter ist trace, Debug ist debug, Info ist info, zwischen Info und Warn ist notice, Warn ist warning, Error ist error, Error+4 und darüber ist critical.
  • SlogOptions.Level legt zusätzlich zu dem des Clients ein Minimum fest; AddSource fügt ein Attribut source mit Funktion, Datei und Zeile des Aufrufers hinzu. Bau mit go 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 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 stop

Flush 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;
  • ErrUnauthorized nach einem 401 oder 403 (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, gibt Flush diesen sofort zurück und sendet nichts;
  • ErrClosed nach Close.

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

FeldStandardBedeutung
Endpointhttps://ingest.lyrelog.comDie Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Einfaches http:// nur für localhost
APIKeyerforderlichDer Server-Schlüssel des Projekts (lyr_srv_...) oder ein Ingest-Schlüssel
Environment$LYRELOG_ENVIRONMENT, sonst productionJeder gültige Name
Platformgoapi, worker...
Releasedie ModulversionWird als resource.app_version gesendet
AppIDder ModulpfadWird als resource.app_id gesendet
MinimumLevelLevelDebugEvents darunter werden verworfen, bevor sie in die Warteschlange kommen
FlushInterval5 sWie oft die Hintergrund-Goroutine sendet
MaxQueue10.000Darüber hinaus fallen die ältesten weg, gezählt in Stats().Dropped
MaxQueueBytes16 MiBDieselbe Grenze, in Bytes
CloseTimeout5 sWie lange Close auf den letzten Flush wartet
HTTPClient30 s TimeoutDer Client, der die Batches sendet. Weiterleitungen werden nie verfolgt, auch nicht mit deinem eigenen Client
ErrorLogstderr, einmalEmpfä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, apikey oder 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.RedactKeys ersetzt die Liste, und ein leeres Slice, das nicht nil ist, schaltet es ab; zum Ergänzen nimmst du RedactKeys: 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 zu MaxQueue. Der Client loggt eine Warnung an ErrorLog (oder stderr) und schweigt dann, bis ein Batch angenommen wurde.
  • Kontext: os_name ist runtime.GOOS, app_build die 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_attrs gezählt, Punkte in Namen werden zu _ (http.status wird http_status), Fehler, Zeitpunkte, Dauern und Stringer werden zu Strings, Structs zu ihrer JSON-Form, NaN zu null. 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 Config oder einen *Client mit fmt ausgibst, wird der API-Schlüssel verborgen.