Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

Go

Des logs structurés depuis vos services Go, avec un handler log/slog. Uniquement la bibliothèque standard.

Serveurs, avec un handler slog

Le module s'appelle go.lyrelog.com/lyrelog. Il nécessite Go 1.24 ou plus récent et n'a aucune dépendance.

Préversion interne : ce package n'est pas encore publié. D'ici là, go get go.lyrelog.com/lyrelog échoue : le dépôt est privé et n'a encore aucune release.

Installation

go get go.lyrelog.com/lyrelog

Démarrage

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)

Utilisez une clé serveur, lyr_srv_..., créée sur la page API keys du projet (Send events from a server). C'est un secret : gardez-la dans l'environnement de votre serveur, jamais dans une app ou une page web. Ses événements sont vérifiés, et le quota journalier par adresse d'expéditeur ne s'applique pas. Une clé d'ingestion, lyr_ing_..., fonctionne aussi, mais ses événements ne sont pas vérifiés.

Seul APIKey est obligatoire : sans lui, New renvoie une erreur et un client nil. Un *Client nil ne fait rien : le code peut donc logger avant d'en avoir un (ou sans). Endpoint vaut par défaut https://ingest.lyrelog.com ; c'est l'URL de base, et un chemin /v1/events:batch collé par erreur est retiré.

log.Fatal et os.Exit ignorent les appels différés : defer client.Close() ne s'exécute donc jamais après eux. Dans main, renvoyez un code de sortie depuis une fonction qui fait le travail :

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
}

Dans une fonction serverless (AWS Lambda), appelez client.Flush(ctx) avant que le handler ne réponde : le runtime peut geler le processus avant l'envoi suivant.

Enregistrer des événements

Une méthode par niveau : Trace, Debug, Info, Notice, Warning, Error, Critical, ou Log(level, message, ...). Les détails sont des options : lyrelog.Category, lyrelog.Attrs, lyrelog.Payload et 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}),
)

Les attributs peuvent être des chaînes, des nombres, des booléens, nil, des slices de chaînes et des maps imbriquées (4 niveaux). Dans les noms, les points sont remplacés par _. Plusieurs options Attrs sont fusionnées, la dernière clé l'emporte. Un Payload est encodé avec encoding/json : passez json.RawMessage pour des octets qui sont déjà du JSON (un simple []byte arrive sous forme de chaîne base64).

Un logger par domaine

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

Utilisateurs

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

Un serveur traite de nombreuses personnes à la fois : définissez l'utilisateur sur chaque événement avec lyrelog.User(id), qui remplace celui de SetUser pour cet événement.

Le handler slog

Envoyez les enregistrements log/slog à Lyrelog :

logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")
  • Le message de l'enregistrement devient le message de l'événement, et son heure l'heure de l'événement ; les attributs et les groupes deviennent des attributs imbriqués.
  • Un attribut chaîne category au premier niveau définit le domaine (et n'est pas envoyé comme attribut) ; sans lui, c'est la Category du handler qui s'applique.
  • Niveaux : Debug-4 et en dessous donnent trace, Debug donne debug, Info donne info, entre Info et Warn, c'est notice, Warn donne warning, Error donne error, Error+4 et au-dessus donnent critical.
  • SlogOptions.Level ajoute un minimum en plus de celui du client ; AddSource ajoute un attribut source avec la fonction, le fichier et la ligne de l'appelant. Compilez avec go build -trimpath pour que le fichier contienne des chemins de module plutôt que les répertoires de votre machine de build.

Pour continuer aussi à afficher les logs dans le terminal, envoyez chaque enregistrement aux deux handlers. À partir de Go 1.26, slog.NewMultiHandler s'en charge :

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

Un middleware net/http

Il n'y a pas de middleware intégré. Celui-ci enregistre chaque requête en http_request_served dans le domaine http, au niveau info, warning pour un 4xx et error pour un 5xx, avec le pattern de la route plutôt que le chemin, pour que les identifiants ne fassent pas exploser la cardinalité :

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 est vide pour une requête qui ne correspond à aucune route.

Erreurs

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

L'événement est exception, de niveau error, avec error_type et error_message dans les attributs et, dans le payload, la chaîne de l'erreur (chaque erreur enveloppée) et la stack. Une erreur nil n'enregistre rien. Logger.CaptureError fait la même chose avec la catégorie du logger. Le niveau est toujours error : pour un autre niveau, enregistrez l'erreur vous-même avec Log.

Panics

Le SDK ne récupère pas les panics. net/http récupère le panic d'un handler et se contente de l'afficher : enregistrez-le donc dans un middleware, placé autour de celui ci-dessus :

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)))

La stack du payload est prise là où le panic a été récupéré : elle montre donc encore les frames qui ont paniqué. Un panic dans une de vos propres goroutines fait planter le programme avant que quoi que ce soit ne soit envoyé : récupérez-le dans cette goroutine de la même façon.

Environnements et plateforme

Environment vaut par défaut la variable d'environnement LYRELOG_ENVIRONMENT (en minuscules), sinon production. Platform vaut par défaut go. Vous pouvez définir l'un ou l'autre dans la configuration :

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

Les deux doivent être composés de lettres minuscules, de chiffres, de - et de _, jusqu'à 32 caractères, et commencer par une lettre ou un chiffre. Un Config.Environment ou un Config.Platform invalide fait renvoyer une erreur à New ; un $LYRELOG_ENVIRONMENT invalide est signalé à ErrorLog et remplacé par production : une faute de frappe dans un déploiement n'arrête donc jamais un service. Release vaut par défaut la version du module principal tirée des informations de build, et AppID le chemin du module principal.

Le consentement concerne les apps qui tournent sur l'appareil de quelqu'un. Un SDK serveur envoie ce qu'on lui donne.

Vider la file et arrêter

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

Flush envoie tout ce qui était en file d'attente avant l'appel et attend que ce soit fait, ou que ctx se termine. Il renvoie :

  • nil quand tout est arrivé au serveur ;
  • ctx.Err() si le contexte s'est terminé avant ;
  • ErrUnauthorized après un 401 ou un 403 (le client arrête d'envoyer jusqu'au redémarrage du processus et garde sa file) ;
  • une erreur indiquant qu'un lot a été refusé et supprimé (le reste a quand même été envoyé) ;
  • une erreur indiquant que l'envoi a échoué et sera retenté, les événements étant conservés. Pendant un Retry-After demandé par le serveur, Flush renvoie aussitôt cette erreur et n'envoie rien ;
  • ErrClosed après Close.

Close attend au plus CloseTimeout pour le dernier envoi et renvoie les mêmes valeurs ; les événements encore non envoyés à ce moment-là sont supprimés et comptés dans Stats().Dropped. Après Close, les appels de log ne font plus rien.

client.Stats() renvoie Queued (en attente, y compris un lot en cours de nouvelle tentative), Sent (acceptés par le serveur), Rejected (lignes refusées par le serveur, jamais renvoyées) et Dropped (par le client : file pleine, lot refusé, ou restants au moment de Close).

En développement et dans les tests

Sans APIKey, New renvoie une erreur et un client nil, et un client nil ne fait rien : le même code tourne dans les tests et sur un portable sans clé, comme dans l'exemple run ci-dessus. Le handler slog posé sur un client nil supprime tous les enregistrements.

Pour voir ce qu'un test enregistre, passez un HTTPClient dont le Transport enregistre les requêtes, ou faites pointer Endpoint vers un httptest.Server (le http:// simple est autorisé pour les adresses de loopback).

Événements vérifiés

Un événement vérifié est un événement qui ne peut pas avoir été envoyé par quelqu'un qui aurait copié la clé d'ingestion publique depuis une app ou une page web. Ce que cela prouve, et ce que cela ne prouve pas, est expliqué dans Événements vérifiés.

Envoyez avec une clé serveur, lyr_srv_.... Chaque événement qu'elle envoie est vérifié (verified_by vaut server) et ne compte pas dans le quota journalier d'une adresse. Un propriétaire la crée sur la page API keys du projet, Send events from a server, après s'être connecté récemment (dans les 10 dernières minutes), et elle n'est affichée qu'une fois. C'est un secret : gardez-la hors du dépôt et lisez-la depuis l'environnement ou le gestionnaire de secrets du serveur.

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

Pour contrôler, ouvrez l'explorer : dans Filter, choisissez Verified by et Server key (les autres valeurs sont App Attest et Not verified). Un événement ouvert l'indique sous Context, dans sa ligne Sender : Verified, server key, ou Not verified, public key.

Les événements envoyés avec une clé d'ingestion, lyr_ing_..., ou une clé d'accès complet, lyr_adm_..., arrivent non vérifiés : n'importe qui détenant une clé publique aurait pu envoyer les mêmes, et ils comptent dans le quota journalier. Un événement vérifié prouve qui l'a envoyé, pas que ce qu'il dit est vrai.

Voir Événements vérifiés pour savoir qui vérifie quoi et comment fonctionne le quota journalier.

Configuration

ChampPar défautSignification
Endpointhttps://ingest.lyrelog.comL'URL de base ; un chemin /v1/... collé est retiré. Le http:// simple uniquement pour localhost
APIKeyobligatoireLa clé serveur du projet (lyr_srv_...), ou une clé d'ingestion
Environment$LYRELOG_ENVIRONMENT, sinon productionN'importe quel nom valide
Platformgoapi, worker...
Releasela version du moduleEnvoyé comme resource.app_version
AppIDle chemin du moduleEnvoyé comme resource.app_id
MinimumLevelLevelDebugLes événements en dessous sont supprimés avant la mise en file d'attente
FlushInterval5 sLa fréquence d'envoi de la goroutine d'arrière-plan
MaxQueue10 000Au-delà, les plus anciens sont supprimés et comptés dans Stats().Dropped
MaxQueueBytes16 MiBLa même limite, en octets
CloseTimeout5 sLe temps pendant lequel Close attend le dernier envoi
HTTPClienttimeout de 30 sLe client qui envoie les lots. Les redirections ne sont jamais suivies, même avec votre propre client
ErrorLogstderr, une foisReçoit les diagnostics propres au SDK, chacun commençant par lyrelog: . Sans lui, seuls la première clé refusée ou le premier lot supprimé et l'avertissement de quota sont écrits sur stderr. Ne le faites pas pointer vers un logger qui alimente ce client

Envoi et limites

  • Une goroutine d'arrière-plan regroupe jusqu'à 500 événements ou 512 KiB par lot, compressés en gzip ; un lot plein part immédiatement. Utilisable en parallèle depuis plusieurs goroutines.
  • Nouvelles tentatives avec full jitter (1 s, doublé à chaque tentative jusqu'à 5 min), en respectant Retry-After (en secondes ou sous forme de date), les mêmes octets étant renvoyés. Tout autre code 4xx supprime le lot ; un 3xx le supprime et écrit un avertissement.
  • Les valeurs sous des clés dont le nom est ou se termine par authorization, cookie, password, token, secret, apikey et le reste de la liste commune deviennent "[redacted]" avant la mise en file d'attente : dans les attributs et le payload, à toute profondeur (maps, structs par leurs noms JSON, slices, http.Header), avant toute troncature. Config.RedactKeys remplace la liste, et une slice vide non nil désactive le masquage ; pour la compléter, RedactKeys: append(lyrelog.DefaultRedactKeys(), "pin").
  • Quand une organisation Free a utilisé les événements de son mois, le serveur répond 429. Les événements restent en mémoire et partent dès que le serveur les accepte de nouveau, dans la limite de MaxQueue. Le client écrit un seul avertissement dans ErrorLog (ou sur stderr) et ne dit plus rien jusqu'à ce qu'un lot soit accepté.
  • Contexte : os_name vaut runtime.GOOS, app_build la révision VCS quand le binaire en a une, et les identifiants d'installation et de session sont propres à chaque processus.
  • Les limites sont appliquées avant la mise en file d'attente : les attributs au-delà de 200 feuilles (les valeurs imbriquées comptées une à une) sont supprimés et comptés dans lyrelog_dropped_attrs, les points dans les noms deviennent _ (http.status devient http_status), les erreurs, dates, durées et Stringer deviennent des chaînes, les structs leur forme JSON, NaN devient null. Un payload de plus de 64 KiB devient {"lyrelog_truncated": true, "bytes": N, "preview": "..."} avec son premier KiB. Les attributs d'un événement sont plafonnés à 256 KiB une fois encodés, et un événement qui ne tient pas dans un lot de 512 KiB est supprimé et compté.
  • Afficher une Config ou un *Client avec fmt masque la clé d'API.