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

JavaScript

Strukturierte Logs von einer Website oder einem Node-Service. TypeScript, ESM, keine Abhängigkeiten.

Browser und Node

Ein Paket, @lyrelog/js, für Browser und Node 22.12 oder neuer. Derselbe Import funktioniert überall: Bundler nehmen den Browser-Build, Node nimmt den Node-Build. Das Paket ist reines ESM: Du kannst es per import laden oder per require() (Node 22.12 lädt ES-Module ohne Flag).

Interne Vorschau: Dieses Paket ist noch nicht veröffentlicht. Bis dahin schlägt pnpm add @lyrelog/js fehl: Auf npm gibt es kein solches Paket.

Installation

pnpm add @lyrelog/js

Starten

Lyrelog.init gibt einen Client zurück. Erstelle einen pro Seitenaufruf oder pro Prozess, so früh wie möglich.

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",
});

Im Browser verwendest du den Ingest-Schlüssel des Projekts, lyr_ing_...: Er kann nur Events anhängen und ist deshalb in einer Seite sicher. Unter Node verwendest du einen Server-Schlüssel, lyr_srv_...: Seine Events sind verifiziert, und das Tageslimit für die Adresse eines einzelnen Absenders gilt für sie nicht. Ein Server-Schlüssel gehört nie in Browser-Code. Wenn du verifizierte Events aus einer Seite willst, schick sie über deinen eigenen Server.

Events gehen an https://ingest.lyrelog.com. Gib endpoint nur an, wenn du sie woandershin schicken willst. Das ist die Basis-URL; ein eingefügter Pfad .../v1/events:batch wird entfernt.

Rufst du init erneut mit demselben Endpoint und Schlüssel auf, bekommst du den laufenden Client zurück, wenn die Konfiguration gleich ist. Andernfalls wird er geschlossen und ein neuer gestartet, sodass ein Hot Reload nie zwei Clients hinterlässt. Ohne apiKey oder mit einem Endpoint, der kein https ist (reines http nur auf localhost), warnt der Client einmal in der Konsole und sendet nichts.

Content Security Policy

Wenn deine Website eine Content Security Policy setzt, erlaube den Ingest in connect-src:

Content-Security-Policy: connect-src 'self' https://ingest.lyrelog.com

Events loggen

Eine Methode pro Level: trace, debug, info, notice, warning, error, critical oder 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 } });

Ein Log-Aufruf passt das Event an die Limits des Servers an, serialisiert es (spätere Änderungen an deinen Objekten wirken sich nicht mehr aus) und stellt es in die Warteschlange. Ungültige Eingaben werden in etwas Gültiges umgewandelt, statt eine Exception auszulösen. Nach close() tun Log-Aufrufe nichts mehr.

Logger für jeden Bereich

const jobs = log.logger("jobs");
jobs.info("job_done", { attrs: { job: "digest", ms: 412 } });

Ein Logger hat alle Level-Methoden und log. Um einen Fehler in seinem Bereich zu erfassen, verwende log.captureException(error, { category: "jobs" }).

Nutzer

log.setUser(accountId); // attached to every following event
log.setUser(null);      // on sign-out

log.sessionId liefert die aktuelle Session, zum Beispiel für einen Support-Screen. Die User-ID wird nicht gespeichert: Im Browser rufst du setUser bei jedem Seitenaufruf erneut auf, sobald du weißt, wer die Person ist.

Screens

log.screen("Checkout");

Loggt screen_viewed im Bereich navigation mit dem vorherigen Screen und den Sekunden, die darauf verbracht wurden, und jedes folgende Event trägt screen. Im Web rufst du es auf, wenn die Seite wechselt. Gib dem Screen einen Namen, statt die URL zu übergeben: /orders/1234 würde einen Screen pro Bestellung erzeugen.

function OrderPage() {
  useEffect(() => log.screen("Order"), []);
  // ...
}

Requests

Requests werden nicht automatisch geloggt. Logge die Requests, die dich interessieren, mit einem stabilen Namen und den Feldern, die du in Diagrammen sehen willst, so wie es das Swift-SDK macht:

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" } });
}

Zeichnet exception auf (Level error, oder level, wenn du eines übergibst), mit error_type und error_message als Attributen sowie Name, Nachricht, Stack, code und bis zu drei causes im Payload. Alles, was geworfen wird, funktioniert, nicht nur Error. Von einem geworfenen Wert, der kein Error ist, werden nur name, message, code und status behalten, nie der Rest des Objekts (der Fehler eines HTTP-Clients würde sonst dessen Request-Header mitschleppen). Im Browser verlieren URLs in Stacks ihren Query-String und ihr Fragment.

Nicht abgefangene Fehler

Sie werden automatisch erfasst, als dasselbe exception-Event mit handled: false und einem mechanism:

  • Im Browser Fehler, die bis window durchkommen (onerror), und Promises, die ohne Handler abgelehnt werden (onunhandledrejection). Die Konsole zeigt sie weiterhin an. Der undurchsichtige Cross-Origin-Fehler „Script error.“ enthält nichts Brauchbares und wird übersprungen.
  • Unter Node eine nicht abgefangene Exception oder Rejection. Lyrelog schaut nur zu (es verwendet uncaughtExceptionMonitor), der Prozess stürzt also genauso ab wie ohne Lyrelog. Vor dem Beenden bleibt keine Zeit zum Senden, deshalb wird das Event in eine kleine Datei im Temp-Ordner geschrieben und beim nächsten Start der App mit demselben Schlüssel gesendet.

Höchstens 10 pro Minute werden erfasst, und derselbe Fehler nur einmal alle 10 Sekunden, damit eine Schleife, die wirft, dein Projekt nicht fluten kann; stats().skippedErrors zählt, was übersprungen wurde. Mit captureErrors: false schaltest du das alles ab.

Fehler, die dein Framework abfängt

Fehler, die ein Framework selbst abfängt, werden nie zu nicht abgefangenen Fehlern: Ruf dort captureException auf. In React aus einer 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;
  }
}

In Express aus einem Error-Handler, der nach deinen Routen registriert wird:

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

Umgebungen und Plattform

  • Node: environment ist nur dann production, wenn NODE_ENV=production gilt. Alles andere, auch ein fehlendes NODE_ENV, ist development: Setz NODE_ENV=production (oder environment) auf deinen Servern. platform ist node.
  • Browser: environment ist development auf localhost, 127.0.0.1, [::1] oder einem .localhost-Host, sonst production. platform ist web.

Beides kannst du in init setzen, zum Beispiel Lyrelog.init({ apiKey, environment: "staging" }). Jeder Name funktioniert: Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen.

const log = Lyrelog.init({ apiKey, consent: "pending" });
// later
log.setConsent("granted"); // or "denied"

pending hält Events ungesendet im Speicher, granted sendet sie, denied verwirft alles (und unter Node auch die Datei mit nicht abgefangenen Fehlern, die noch gesendet werden sollten). Die Einwilligung wird zwischen Seitenaufrufen nicht gespeichert: Speichere die Entscheidung der Person selbst und übergib sie an init. Im Browser bleiben Installations- und Session-ID im Speicher, bis die Einwilligung erteilt ist, nicht in localStorage oder sessionStorage.

Schwärzen und Filtern

Ein Wert wird zu "[redacted]", in Attributen, im Payload und in allem, was in einen String umgewandelt wird, wenn sein Schlüsselname, kleingeschrieben und ohne -, _, . oder Leerzeichen, einer der folgenden ist oder auf einen davon endet: authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential, credentials, accesskey oder signature. X-Api-Key, csrf_token, Set-Cookie und user_token werden also geschwärzt, token_count und max_tokens nicht. redactKeys ersetzt diese Liste durch deine eigenen Namen, die genauso abgeglichen werden; eine leere Liste schaltet das Schwärzen ab. Um die Standardliste zu ergänzen, übernimm DEFAULT_REDACT_KEYS, das das Paket exportiert, per Spread in deine Liste.

Um Events selbst zu ändern oder zu verwerfen, übergib beforeSend. Die Funktion bekommt jedes Event nach dem Schwärzen und bevor es in die Warteschlange kommt, und gibt es zurück, geändert oder nicht, oder null, um es zu verwerfen. Die IDs, ts und resource lassen sich nicht ändern, was du zurückgibst, wird erneut an die Limits angepasst, und ein Hook, der wirft, verwirft das Event.

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;
  },
});

Flush und Stopp

Im Browser brauchst du beides selten: Der Timer und das Ausblenden der Seite senden bereits.

await log.flush(); // send what is queued now

Unter Node schließt du den Client in deinem Shutdown-Pfad, damit alles in der Warteschlange rausgeht, bevor der Prozess endet:

process.on("SIGTERM", async () => {
  await log.close(); // sends what is queued, then stops
  process.exit(0);
});

Ein Skript, das mit process.exit() endet, überspringt beforeExit und verliert, was noch in der Warteschlange liegt: Ruf vorher await log.close() auf, wie oben.

In einer Serverless-Funktion (AWS Lambda, Vercel- und Netlify-Functions, Cloudflare Workers) friert die Laufzeitumgebung die Funktion ein oder beendet sie, sobald sie antwortet, also bevor der Timer feuert. Flushe vor dem Return:

export async function handler(event) {
  log.info("order_created", { attrs: { order_id: event.id } });
  await log.flush();
  return { statusCode: 200 };
}

flush, close und das Senden beim Ausblenden der Seite respektieren alle ein Retry-After, das der Server verlangt hat: Während eines solchen kehrt flush sofort zurück und die Events warten.

log.stats() gibt { queued, queuedBytes, dropped, delivered, rejected, skippedErrors, disabled } zurück; disabled ist true nach einem 401 oder 403 oder wenn der Client keinen Schlüssel oder Endpoint zum Senden hat.

In Entwicklung und Tests

Lass apiKey leer, dann warnt der Client einmal und sendet nichts. Oder übergib consent: "denied", um jedes Event ohne Warnung zu verwerfen:

const log = Lyrelog.init({
  apiKey: process.env.LYRELOG_KEY ?? "",
  consent: process.env.NODE_ENV === "test" ? "denied" : "granted",
});

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.

Unter Node sendest du 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.

export const log = Lyrelog.init({
  apiKey: process.env.LYRELOG_KEY!, // lyr_srv_..., set in the server's environment
});

Im Browser ist der Schlüssel der öffentliche Ingest-Schlüssel, deshalb kommen die Events einer Seite unverifiziert an und zählen zum Tagesanteil. Ein Server-Schlüssel gehört nie in Browser-Code: Alles in der Seite kann ausgelesen werden. Um die Events einer Website zu verifizieren, leite sie über deinen eigenen Server weiter: Richte endpoint auf eine Route in deinem Backend, die jeden Batch mit dem Server-Schlüssel weiterleitet. Diese Route darf nur Events aus deinen eigenen angemeldeten Sessions annehmen, sonst verifiziert sie gar nichts.

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 oder einem Vollzugriffs-Schlüssel, lyr_adm_..., gesendet werden, kommen unverifiziert an: Jeder mit einem öffentlichen Schlüssel hätte dasselbe senden können. 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

OptionStandardBedeutung
endpointhttps://ingest.lyrelog.comDie Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur auf localhost
apiKeyerforderlichBrowser: der Ingest-Schlüssel des Projekts, sicher in Client-Code. Node: ein Server-Schlüssel, nie in Client-Code. Ohne ihn sendet der Client nichts
environmenterkanntJeder Name: Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen
platformweb / nodeapi, worker...
releaseNode: npm_package_versionWird als app_version gesendet. Den Standard gibt es nur beim Start über ein Package-Script: Unter node server.js, Docker oder systemd übergibst du ihn selbst
appIdWeb: der Hostname. Node: npm_package_nameWird als app_id gesendet. Unter Node gilt dieselbe Einschränkung wie bei release
minimumLeveldebugEvents darunter werden verworfen, bevor sie in die Warteschlange kommen
flushIntervalMs5000Wie oft die Warteschlange gesendet wird
maxQueue10000Events, die im Speicher warten; darüber hinaus fallen die ältesten weg
maxQueueBytes16 MiBDieselbe Grenze, in Bytes
redactKeysDEFAULT_REDACT_KEYSZu schwärzende Schlüsselnamen; ersetzt die Standardliste, [] schaltet es ab
beforeSendkeinerÄndert ein Event, oder gib null zurück, um es zu verwerfen
consentgrantedgranted, pending oder denied
captureErrorstrueErfasst nicht abgefangene Fehler und unbehandelte Rejections

Zustellung und Limits

Wann gesendet wirdAlle 5 s, sobald 500 Events warten, bei flush() und close(). Im Browser zusätzlich, wenn die Seite ausgeblendet wird; unter Node bei beforeExit (nicht bei process.exit(); der Timer hält den Prozess nie am Leben).
BatchesBis zu 500 Events oder 512 KiB, NDJSON, gzip (CompressionStream in Browsern, zlib unter Node). Ein Event über 1 MiB wird verworfen und gezählt.
WiederholungenBackoff mit Full Jitter (1 s, verdoppelt bis 5 min), unter Beachtung von Retry-After. Eine Wiederholung sendet dieselben Events mit denselben IDs erneut. Jeder andere 4xx-Status verwirft den Batch; ein 3xx-Status verwirft ihn mit einer Warnung (Weiterleitungen werden nicht verfolgt); ein abgelehnter Schlüssel stoppt das Senden bis zum Neustart und behält die Events.
MonatskontingentWenn eine Free-Organisation die Events ihres Monats aufgebraucht hat, antwortet der Server mit 429. Die Events bleiben in der Warteschlange und gehen raus, sobald der Server sie wieder annimmt, bis zu maxQueue. Der Client loggt ein console.warn mit der Nachricht des Servers, und erst dann wieder, wenn zwischendurch ein Batch angenommen wurde.
Eigene ProblemeEin falscher Endpoint, eine Weiterleitung oder ein verworfener Batch: ein console.warn, das mit [lyrelog] beginnt. Ein abgelehnter Schlüssel und abgelehnte Zeilen: console.debug, also schalte in der Browser-Konsole die ausführlichen Meldungen ein, um sie zu sehen.
KontextWeb: os_name: "web", die Browser-Familie als device_model, navigator.language als locale, eine Installations-ID in localStorage und eine Session-ID in sessionStorage (neu nach 30 min Inaktivität). Node: process.platform, os.release(), die CPU-Architektur und IDs pro Prozess. Speicher, der wirft (privater Modus), fällt auf den Arbeitsspeicher zurück.
LimitsWerden vor dem Einreihen angewendet; überzählige Attribute werden in lyrelog_dropped_attrs gezählt, Punkte in Attributnamen werden zu _, ein Payload über 64 KiB wird zu einer Zusammenfassung mit Vorschau.

Gut zu wissen:

  • Die Warteschlange liegt im Arbeitsspeicher. Events, die noch warten, wenn ein Tab endgültig geschlossen oder ein Prozess mit SIGKILL beendet wird oder mit process.exit() endet, gehen verloren. Ruf close() im Shutdown-Pfad deines Servers auf und flush() am Ende eines Serverless-Handlers.
  • Eine ausgeblendete Seite sendet höchstens etwa 60 KB, der Rest wartet, bis die Seite wieder sichtbar wird.
  • Der Ingest-Schlüssel ist im Web öffentlich. Jeder, der deine Seite liest, kann ebenfalls Events an das Projekt senden, behandle eingehende Events also nicht als vertrauenswürdige Eingaben. Diese Events sind nicht verifiziert; Events von Node mit einem Server-Schlüssel schon.