JavaScript
Des logs structurés depuis un site web ou un service Node. TypeScript, ESM, aucune dépendance.
Un seul package, @lyrelog/js, pour les navigateurs et Node 22.12 ou plus récent. Le même import
fonctionne partout : les bundlers prennent le build navigateur, Node prend le build Node. Le package
est uniquement ESM : importez-le avec import, ou avec require() (Node 22.12 charge les modules ES
sans option).
Préversion interne : ce package n'est pas encore publié. D'ici là, pnpm add @lyrelog/js échoue :
il n'existe aucun package sur npm.
Installation
pnpm add @lyrelog/jsDémarrage
Lyrelog.init renvoie un client. Créez-en un par chargement de page ou par processus, le plus tôt
possible.
import { Lyrelog } from "@lyrelog/js";
export const log = Lyrelog.init({
apiKey: "lyr_ing_...", // ingest-only: it can append events, never read them
release: "2.0.1",
});Dans le navigateur, utilisez la clé d'ingestion du projet, lyr_ing_... : elle ne peut qu'ajouter
des événements, elle peut donc figurer dans une page sans risque. Sous Node, utilisez une clé
serveur, lyr_srv_... : ses événements sont vérifiés et le quota journalier par
adresse d'expéditeur ne s'applique pas. Ne mettez jamais une clé serveur dans du code exécuté par le
navigateur. Pour obtenir des événements vérifiés depuis une page, envoyez-les
par votre propre serveur.
Les événements partent vers https://ingest.lyrelog.com. Ne passez endpoint que pour les envoyer
ailleurs. C'est l'URL de base ; un chemin .../v1/events:batch collé par erreur est retiré.
Rappeler init avec le même endpoint et la même clé renvoie le client déjà actif si la configuration est
identique ; sinon, ce client est fermé et un nouveau démarre. Un hot reload ne laisse donc jamais deux
clients. Sans apiKey, ou avec un endpoint qui n'est pas en https (le http simple n'est accepté
que sur localhost), le client affiche un avertissement une seule fois dans la console et n'envoie
rien.
Content Security Policy
Si votre site définit une Content Security Policy, autorisez l'ingestion dans connect-src :
Content-Security-Policy: connect-src 'self' https://ingest.lyrelog.comEnregistrer des événements
Une méthode par niveau : trace, debug, info, notice, warning, error, critical, ou
log(level, message, options).
log.info("checkout_done", { category: "checkout", attrs: { items: 3, total_cents: 4200 } });
log.error("job_failed", { attrs: { job: "digest" }, payload: { response: raw } });Un appel de log ajuste l'événement aux limites du serveur, le sérialise (les modifications
ultérieures de vos objets n'y apparaissent pas) et le met en file d'attente. Une entrée invalide
est transformée en quelque chose de valide, jamais en exception. Après close(), les appels de log
ne font plus rien.
Un logger par domaine
const jobs = log.logger("jobs");
jobs.info("job_done", { attrs: { job: "digest", ms: 412 } });Un logger dispose de toutes les méthodes de niveau et de log. Pour capturer une erreur dans son
domaine, utilisez log.captureException(error, { category: "jobs" }).
Utilisateurs
log.setUser(accountId); // attached to every following event
log.setUser(null); // on sign-outlog.sessionId donne la session en cours, par exemple pour un écran de support. L'identifiant
utilisateur n'est pas enregistré : dans le navigateur, rappelez setUser à chaque chargement de
page dès que vous savez qui est la personne.
Écrans
log.screen("Checkout");Enregistre screen_viewed dans le domaine navigation, avec l'écran précédent et les secondes
passées dessus, et chaque événement suivant porte screen. Sur le web, appelez-le quand la page
change. Donnez un nom à l'écran plutôt que de passer l'URL : /orders/1234 créerait un écran par
commande.
function OrderPage() {
useEffect(() => log.screen("Order"), []);
// ...
}Requêtes
Les requêtes ne sont pas enregistrées automatiquement. Enregistrez celles qui vous intéressent avec un nom stable et les champs que vous voulez voir en graphique, comme le fait le SDK Swift :
const started = performance.now();
const res = await fetch("/api/cart");
log.log(res.ok ? "debug" : "warning", res.ok ? "http_request" : "http_request_failed", {
category: "network",
attrs: { method: "GET", path: "/api/cart", status: res.status, duration_ms: Math.round(performance.now() - started) },
});Exceptions
try {
await pay();
} catch (error) {
log.captureException(error, { category: "checkout", attrs: { step: "pay" } });
}Enregistre exception (niveau error, ou level si vous en passez un) avec error_type et
error_message comme attributs, et le nom, le message, la stack, code et jusqu'à trois cause
dans le payload. Toute valeur levée convient, pas seulement une Error. D'une valeur levée qui
n'est pas une Error, seuls name, message, code et status sont conservés, jamais le reste
de l'objet (l'erreur d'un client HTTP contiendrait les headers de sa requête). Dans le navigateur,
les URL des stacks perdent leur query string et leur fragment.
Erreurs non interceptées
Elles sont capturées pour vous, sous la forme du même événement exception avec handled: false
et un mechanism :
- Dans le navigateur, les erreurs qui atteignent
window(onerror) et les promesses rejetées sans gestionnaire (onunhandledrejection). La console les affiche toujours. Le « Script error. » opaque des scripts d'une autre origine ne contient rien d'utile et est ignoré. - Sous Node, une exception ou un rejet non intercepté. Lyrelog se contente d'observer (il
utilise
uncaughtExceptionMonitor), donc le processus plante comme il le ferait sans lui. Il n'y a pas le temps d'envoyer quoi que ce soit avant la sortie : l'événement est écrit dans un petit fichier du dossier temporaire et envoyé au prochain démarrage de l'app avec la même clé.
Au plus 10 erreurs sont capturées par minute, et la même erreur une fois toutes les 10 secondes : une
boucle qui lève des erreurs ne peut pas inonder votre projet. stats().skippedErrors compte ce qui
a été ignoré. Désactivez le tout avec captureErrors: false.
Erreurs interceptées par votre framework
Les erreurs qu'un framework intercepte lui-même ne deviennent jamais non interceptées : appelez
captureException à cet endroit. En React, depuis un error boundary :
import { Component, type ErrorInfo, type ReactNode } from "react";
class ErrorBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
state = { failed: false };
static getDerivedStateFromError() {
return { failed: true };
}
componentDidCatch(error: unknown, info: ErrorInfo) {
log.captureException(error, { category: "ui", attrs: { component_stack: info.componentStack ?? "" } });
}
render() {
return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
}
}En Express, depuis un gestionnaire d'erreurs ajouté après vos routes :
app.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
log.captureException(err, {
category: "http",
attrs: { method: req.method, route: req.route?.path ?? "unmatched" },
});
next(err);
});Environnements et plateforme
- Node :
environmentvautproductionuniquement quandNODE_ENV=production. Tout le reste, y compris l'absence deNODE_ENV, donnedevelopment: définissezNODE_ENV=production(ouenvironment) sur vos serveurs.platformvautnode. - Navigateur :
environmentvautdevelopmentsurlocalhost,127.0.0.1,[::1]ou un hôte en.localhost, sinonproduction.platformvautweb.
Vous pouvez définir l'un ou l'autre dans init, par exemple
Lyrelog.init({ apiKey, environment: "staging" }). N'importe quel nom convient : lettres
minuscules, chiffres, - et _, jusqu'à 32 caractères.
Consentement
const log = Lyrelog.init({ apiKey, consent: "pending" });
// later
log.setConsent("granted"); // or "denied"pending garde les événements en mémoire sans les envoyer, granted les envoie, denied supprime
tout (et, sous Node, le fichier des erreurs non interceptées en attente d'envoi).
Le consentement n'est pas conservé d'un chargement de page à l'autre : enregistrez vous-même le
choix de la personne et passez-le à init. Dans le navigateur, tant que le consentement n'est pas
donné, les identifiants d'installation et de session restent en mémoire, ni dans localStorage ni
dans sessionStorage.
Masquage et filtrage
Une valeur devient "[redacted]", dans les attributs, le payload et tout ce qui est converti en
chaîne, quand le nom de sa clé, en minuscules et sans -, _, . ni espaces, est ou se termine
par l'un de authorization, cookie, password, passwd, secret, token, apikey,
privatekey, credential, credentials, accesskey ou signature. Ainsi X-Api-Key,
csrf_token, Set-Cookie et user_token sont masqués ; token_count et max_tokens ne le sont
pas. redactKeys remplace cette liste par vos propres noms, comparés de la même façon ; une liste
vide désactive le masquage. Pour compléter la liste par défaut, étalez DEFAULT_REDACT_KEYS, que le
package exporte.
Pour modifier ou supprimer vous-même des événements, passez beforeSend. Il reçoit chaque événement
après le masquage et avant sa mise en file d'attente, et le renvoie, modifié ou non, ou renvoie
null pour le supprimer. Les identifiants, ts et resource ne peuvent pas être modifiés, ce que
vous renvoyez est de nouveau ajusté aux limites, et un hook qui lève une exception supprime
l'événement.
import { Lyrelog, DEFAULT_REDACT_KEYS } from "@lyrelog/js";
const log = Lyrelog.init({
apiKey: "lyr_ing_...",
redactKeys: [...DEFAULT_REDACT_KEYS, "card_number"],
beforeSend(event) {
if (event.message === "health_check") return null;
if (event.attrs?.email) event.attrs.email = "[redacted]";
return event;
},
});Vider la file et arrêter
Dans le navigateur, vous n'en avez presque jamais besoin : le minuteur et le passage de la page en arrière-plan déclenchent déjà l'envoi.
await log.flush(); // send what is queued nowSous Node, fermez le client dans votre procédure d'arrêt, pour que ce qui est en file d'attente parte avant la sortie du processus :
process.on("SIGTERM", async () => {
await log.close(); // sends what is queued, then stops
process.exit(0);
});Un script qui se termine par process.exit() ne déclenche pas beforeExit et perd ce qui est encore en file
d'attente : faites d'abord await log.close(), comme ci-dessus.
Dans une fonction serverless (AWS Lambda, les fonctions Vercel et Netlify, Cloudflare Workers), le runtime gèle ou arrête la fonction dès qu'elle a répondu, avant que le minuteur ne se déclenche. Videz la file avant de répondre :
export async function handler(event) {
log.info("order_created", { attrs: { order_id: event.id } });
await log.flush();
return { statusCode: 200 };
}flush, close et l'envoi quand la page est masquée respectent tous un Retry-After demandé par le
serveur : pendant ce délai, flush rend la main aussitôt et les événements attendent.
log.stats() renvoie { queued, queuedBytes, dropped, delivered, rejected, skippedErrors, disabled } ;
disabled vaut true après un 401 ou un 403, ou quand le client n'a ni clé ni endpoint vers
lequel envoyer.
En développement et dans les tests
Laissez apiKey vide : le client affiche un avertissement une fois et n'envoie rien. Ou passez
consent: "denied" pour supprimer tous les événements sans avertissement :
const log = Lyrelog.init({
apiKey: process.env.LYRELOG_KEY ?? "",
consent: process.env.NODE_ENV === "test" ? "denied" : "granted",
});É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.
Sous Node, 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.
export const log = Lyrelog.init({
apiKey: process.env.LYRELOG_KEY!, // lyr_srv_..., set in the server's environment
});Dans un navigateur, la clé est la clé d'ingestion publique : les événements d'une page arrivent donc
non vérifiés et comptent dans le quota journalier. Ne mettez jamais une clé serveur dans du code
exécuté par le navigateur : tout ce qui se trouve dans la page peut être lu. Pour vérifier les
événements d'un site, relayez-les
par votre propre serveur : faites
pointer endpoint vers une route de votre backend qui transmet chaque lot avec la clé serveur.
Cette route ne doit accepter que les événements de vos propres sessions connectées, sinon elle ne
vérifie rien.
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 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. 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
| Option | Par défaut | Signification |
|---|---|---|
endpoint | https://ingest.lyrelog.com | L'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement sur localhost |
apiKey | obligatoire | Navigateur : la clé d'ingestion du projet, sans risque dans le code client. Node : une clé serveur, jamais dans le code client. Sans elle, le client n'envoie rien |
environment | détecté | N'importe quel nom : lettres minuscules, chiffres, - et _, jusqu'à 32 caractères |
platform | web / node | api, worker... |
release | Node : npm_package_version | Envoyé comme app_version. La valeur par défaut n'existe que si l'app est lancée par un script du package : passez-la vous-même avec node server.js, Docker ou systemd |
appId | Web : le nom d'hôte. Node : npm_package_name | Envoyé comme app_id. Sous Node, même réserve que pour release |
minimumLevel | debug | Les événements en dessous sont supprimés avant la mise en file d'attente |
flushIntervalMs | 5000 | La fréquence d'envoi de la file |
maxQueue | 10000 | Les événements en attente en mémoire ; au-delà, les plus anciens sont supprimés |
maxQueueBytes | 16 MiB | La même limite, en octets |
redactKeys | DEFAULT_REDACT_KEYS | Les noms de clés à masquer ; remplace la liste par défaut, [] désactive le masquage |
beforeSend | aucun | Modifier un événement, ou renvoyer null pour le supprimer |
consent | granted | granted, pending ou denied |
captureErrors | true | Capturer les erreurs non interceptées et les rejets non gérés |
Envoi et limites
| Quand il envoie | Toutes les 5 s, dès que 500 événements attendent, sur flush() et close(). Dans le navigateur, aussi quand la page est masquée ; sous Node, sur beforeExit (pas sur process.exit() ; le minuteur ne maintient jamais le processus en vie). |
| Lots | Jusqu'à 500 événements ou 512 KiB, en NDJSON, gzip (CompressionStream dans les navigateurs, zlib sous Node). Un événement de plus de 1 MiB est supprimé et compté. |
| Nouvelles tentatives | Backoff avec full jitter (1 s, doublé à chaque tentative jusqu'à 5 min), en respectant Retry-After. Une nouvelle tentative renvoie les mêmes événements avec les mêmes identifiants. Tout autre code 4xx supprime le lot ; un 3xx le supprime avec un avertissement (les redirections ne sont pas suivies) ; une clé refusée arrête l'envoi jusqu'au redémarrage et conserve les événements. |
| Quota mensuel | Quand une organisation Free a utilisé les événements de son mois, le serveur répond 429. Les événements restent dans la file et partent dès que le serveur les accepte de nouveau, dans la limite de maxQueue. Le client écrit un seul console.warn avec le message du serveur, puis un autre seulement si un lot a été accepté entre-temps. |
| Problèmes du SDK lui-même | Un mauvais endpoint, une redirection ou un lot supprimé : un console.warn commençant par [lyrelog]. Une clé refusée et des lignes rejetées : console.debug, activez donc les messages détaillés dans la console du navigateur pour les voir. |
| Contexte | Web : os_name: "web", la famille du navigateur comme device_model, navigator.language comme locale, un identifiant d'installation dans localStorage et un identifiant de session dans sessionStorage (nouveau après 30 min d'inactivité). Node : process.platform, os.release(), l'architecture du processeur, et des identifiants par processus. Un stockage qui lève une exception (navigation privée) se replie sur la mémoire. |
| Limites | Tout est ajusté avant la mise en file d'attente ; les attributs en trop sont comptés dans lyrelog_dropped_attrs, les points dans les noms d'attributs deviennent _, un payload de plus de 64 KiB devient un résumé avec un aperçu. |
Bon à savoir :
- La file d'attente vit en mémoire. Les événements encore en attente quand un onglet se ferme
définitivement, ou quand un processus est tué avec
SIGKILLou se termine parprocess.exit(), sont perdus. Appelezclose()dans la procédure d'arrêt de votre serveur, etflush()à la fin d'un handler serverless. - Une page qui se masque envoie au plus 60 KB environ, le reste attend que la page revienne.
- Sur le web, la clé d'ingestion est publique. Quiconque lit votre page peut aussi envoyer des événements au projet : ne traitez donc pas les événements reçus comme des données de confiance. Ces événements ne sont pas vérifiés ; ceux envoyés depuis Node avec une clé serveur le sont.