JavaScript
Strukturierte Logs von einer Website oder einem Node-Service. TypeScript, ESM, keine Abhängigkeiten.
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/jsStarten
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.comEvents 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-outlog.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
windowdurchkommen (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:
environmentist nur dannproduction, wennNODE_ENV=productiongilt. Alles andere, auch ein fehlendesNODE_ENV, istdevelopment: SetzNODE_ENV=production(oderenvironment) auf deinen Servern.platformistnode. - Browser:
environmentistdevelopmentauflocalhost,127.0.0.1,[::1]oder einem.localhost-Host, sonstproduction.platformistweb.
Beides kannst du in init setzen, zum Beispiel Lyrelog.init({ apiKey, environment: "staging" }).
Jeder Name funktioniert: Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen.
Einwilligung
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 nowUnter 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
| Option | Standard | Bedeutung |
|---|---|---|
endpoint | https://ingest.lyrelog.com | Die Basis-URL; ein eingefügter Pfad /v1/... wird entfernt. Nur https, http nur auf localhost |
apiKey | erforderlich | Browser: 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 |
environment | erkannt | Jeder Name: Kleinbuchstaben, Ziffern, - und _, bis zu 32 Zeichen |
platform | web / node | api, worker... |
release | Node: npm_package_version | Wird 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 |
appId | Web: der Hostname. Node: npm_package_name | Wird als app_id gesendet. Unter Node gilt dieselbe Einschränkung wie bei release |
minimumLevel | debug | Events darunter werden verworfen, bevor sie in die Warteschlange kommen |
flushIntervalMs | 5000 | Wie oft die Warteschlange gesendet wird |
maxQueue | 10000 | Events, die im Speicher warten; darüber hinaus fallen die ältesten weg |
maxQueueBytes | 16 MiB | Dieselbe Grenze, in Bytes |
redactKeys | DEFAULT_REDACT_KEYS | Zu schwärzende Schlüsselnamen; ersetzt die Standardliste, [] schaltet es ab |
beforeSend | keiner | Ändert ein Event, oder gib null zurück, um es zu verwerfen |
consent | granted | granted, pending oder denied |
captureErrors | true | Erfasst nicht abgefangene Fehler und unbehandelte Rejections |
Zustellung und Limits
| Wann gesendet wird | Alle 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). |
| Batches | Bis zu 500 Events oder 512 KiB, NDJSON, gzip (CompressionStream in Browsern, zlib unter Node). Ein Event über 1 MiB wird verworfen und gezählt. |
| Wiederholungen | Backoff 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. |
| Monatskontingent | Wenn 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 Probleme | Ein 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. |
| Kontext | Web: 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. |
| Limits | Werden 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
SIGKILLbeendet wird oder mitprocess.exit()endet, gehen verloren. Rufclose()im Shutdown-Pfad deines Servers auf undflush()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.