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

JavaScript

Des logs structurés depuis un site web ou un service Node. TypeScript, ESM, aucune dépendance.

Navigateurs et Node

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

Dé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.com

Enregistrer 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-out

log.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 : environment vaut production uniquement quand NODE_ENV=production. Tout le reste, y compris l'absence de NODE_ENV, donne development : définissez NODE_ENV=production (ou environment) sur vos serveurs. platform vaut node.
  • Navigateur : environment vaut development sur localhost, 127.0.0.1, [::1] ou un hôte en .localhost, sinon production. platform vaut web.

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.

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 now

Sous 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

OptionPar défautSignification
endpointhttps://ingest.lyrelog.comL'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement sur localhost
apiKeyobligatoireNavigateur : 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
environmentdétectéN'importe quel nom : lettres minuscules, chiffres, - et _, jusqu'à 32 caractères
platformweb / nodeapi, worker...
releaseNode : npm_package_versionEnvoyé 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
appIdWeb : le nom d'hôte. Node : npm_package_nameEnvoyé comme app_id. Sous Node, même réserve que pour release
minimumLeveldebugLes événements en dessous sont supprimés avant la mise en file d'attente
flushIntervalMs5000La fréquence d'envoi de la file
maxQueue10000Les événements en attente en mémoire ; au-delà, les plus anciens sont supprimés
maxQueueBytes16 MiBLa même limite, en octets
redactKeysDEFAULT_REDACT_KEYSLes noms de clés à masquer ; remplace la liste par défaut, [] désactive le masquage
beforeSendaucunModifier un événement, ou renvoyer null pour le supprimer
consentgrantedgranted, pending ou denied
captureErrorstrueCapturer les erreurs non interceptées et les rejets non gérés

Envoi et limites

Quand il envoieToutes 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).
LotsJusqu'à 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 tentativesBackoff 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 mensuelQuand 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êmeUn 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.
ContexteWeb : 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.
LimitesTout 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 SIGKILL ou se termine par process.exit(), sont perdus. Appelez close() dans la procédure d'arrêt de votre serveur, et flush() à 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.