Go
Des logs structurés depuis vos services Go, avec un handler log/slog. Uniquement la bibliothèque standard.
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/lyrelogDé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 itUn 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
categoryau premier niveau définit le domaine (et n'est pas envoyé comme attribut) ; sans lui, c'est laCategorydu handler qui s'applique. - Niveaux :
Debug-4et en dessous donnenttrace,Debugdonnedebug,Infodonneinfo, entreInfoetWarn, c'estnotice,Warndonnewarning,Errordonneerror,Error+4et au-dessus donnentcritical. SlogOptions.Levelajoute un minimum en plus de celui du client ;AddSourceajoute un attributsourceavec la fonction, le fichier et la ligne de l'appelant. Compilez avecgo build -trimpathpour 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.
Consentement
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 stopFlush 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 :
nilquand tout est arrivé au serveur ;ctx.Err()si le contexte s'est terminé avant ;ErrUnauthorizedaprès un401ou un403(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-Afterdemandé par le serveur,Flushrenvoie aussitôt cette erreur et n'envoie rien ; ErrClosedaprèsClose.
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
| Champ | Par défaut | Signification |
|---|---|---|
Endpoint | https://ingest.lyrelog.com | L'URL de base ; un chemin /v1/... collé est retiré. Le http:// simple uniquement pour localhost |
APIKey | obligatoire | La clé serveur du projet (lyr_srv_...), ou une clé d'ingestion |
Environment | $LYRELOG_ENVIRONMENT, sinon production | N'importe quel nom valide |
Platform | go | api, worker... |
Release | la version du module | Envoyé comme resource.app_version |
AppID | le chemin du module | Envoyé comme resource.app_id |
MinimumLevel | LevelDebug | Les événements en dessous sont supprimés avant la mise en file d'attente |
FlushInterval | 5 s | La fréquence d'envoi de la goroutine d'arrière-plan |
MaxQueue | 10 000 | Au-delà, les plus anciens sont supprimés et comptés dans Stats().Dropped |
MaxQueueBytes | 16 MiB | La même limite, en octets |
CloseTimeout | 5 s | Le temps pendant lequel Close attend le dernier envoi |
HTTPClient | timeout de 30 s | Le client qui envoie les lots. Les redirections ne sont jamais suivies, même avec votre propre client |
ErrorLog | stderr, une fois | Reç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,apikeyet 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.RedactKeysremplace 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 deMaxQueue. Le client écrit un seul avertissement dansErrorLog(ou sur stderr) et ne dit plus rien jusqu'à ce qu'un lot soit accepté. - Contexte :
os_namevautruntime.GOOS,app_buildla 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.statusdevienthttp_status), les erreurs, dates, durées etStringerdeviennent des chaînes, les structs leur forme JSON, NaN devientnull. 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
Configou un*Clientavecfmtmasque la clé d'API.