Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

JavaScript

Logs estructurados desde un sitio web o un servicio Node. TypeScript, ESM, sin dependencias.

Navegadores y Node

Un solo paquete, @lyrelog/js, para navegadores y para Node 22.12 o posterior. El mismo import funciona en todas partes: los bundlers eligen la versión para navegador y Node elige la de Node. El paquete es solo ESM: impórtalo con import o con require() (Node 22.12 carga módulos ES sin ningún flag).

Vista previa interna: este paquete aún no está publicado. Hasta entonces, pnpm add @lyrelog/js falla: no hay ningún paquete en npm.

Instalación

pnpm add @lyrelog/js

Primeros pasos

Lyrelog.init devuelve un cliente. Crea uno por carga de página o por proceso, lo antes posible.

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

En el navegador, usa la clave de ingesta del proyecto, lyr_ing_...: solo puede añadir eventos, así que es segura en una página. En Node, usa una clave de servidor, lyr_srv_...: sus eventos están verificados y no se les aplica la cuota diaria de una dirección. Nunca pongas una clave de servidor en código de navegador. Para tener eventos verificados desde una página, envíalos a través de tu propio servidor.

Los eventos van a https://ingest.lyrelog.com. Pasa endpoint solo para enviarlos a otro sitio. Es la URL base; si pegas una ruta .../v1/events:batch, se quita.

Volver a llamar a init con el mismo endpoint y la misma clave devuelve el cliente activo si la configuración es la misma; si no, lo cierra y arranca uno nuevo, así que una recarga en caliente nunca deja dos clientes. Sin apiKey, o con un endpoint que no sea https (http sin cifrar solo en localhost), el cliente avisa una vez en la consola y no envía nada.

Content Security Policy

Si tu sitio define una Content Security Policy, permite la ingesta en connect-src:

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

Registrar eventos

Un método por nivel: trace, debug, info, notice, warning, error, critical, o 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 } });

Cada llamada ajusta el evento a los límites del servidor, lo serializa (los cambios posteriores en tus objetos no se cuelan) y lo pone en la cola. Una entrada incorrecta se convierte en algo válido, nunca en una excepción. Después de close(), las llamadas de registro no hacen nada.

Loggers por área

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

Un logger tiene todos los métodos de nivel y log. Para capturar un error en su área, usa log.captureException(error, { category: "jobs" }).

Usuarios

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

log.sessionId te da la sesión actual, por ejemplo para una pantalla de soporte. El id de usuario no se guarda: en el navegador, vuelve a llamar a setUser en cada carga de página en cuanto sepas quién es la persona.

Pantallas

log.screen("Checkout");

Registra screen_viewed en el área navigation con la pantalla anterior y los segundos que se pasaron en ella, y todos los eventos siguientes llevan screen. En la web, llámalo cuando cambie la página. Ponle un nombre a la pantalla en lugar de pasar la URL: /orders/1234 crearía una pantalla por pedido.

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

Peticiones

No hay registro automático de peticiones. Registra las que te interesen con un nombre estable y los campos que quieras graficar, como hace el SDK de 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) },
});

Excepciones

try {
  await pay();
} catch (error) {
  log.captureException(error, { category: "checkout", attrs: { step: "pay" } });
}

Registra exception (nivel error, o level si pasas uno) con error_type y error_message como atributos, y el nombre, el mensaje, el stack, code y hasta tres cause en el payload. Funciona con cualquier cosa que se lance, no solo con Error. De un valor lanzado que no sea un Error solo se guardan name, message, code y status, nunca el resto del objeto (el error de un cliente HTTP llevaría las cabeceras de su petición). En el navegador, las URL de los stacks pierden la query string y el fragmento.

Errores no capturados

Se capturan por ti, como el mismo evento exception con handled: false y un mechanism:

  • En el navegador, los errores que llegan a window (onerror) y las promesas rechazadas sin handler (onunhandledrejection). La consola los sigue mostrando. El opaco "Script error." de otro origen no aporta nada útil y se omite.
  • En Node, una excepción o un rechazo no capturados. Lyrelog solo observa (usa uncaughtExceptionMonitor), así que el proceso se cae igual que lo haría sin él. No hay tiempo de enviar nada antes de que termine, así que el evento se escribe en un pequeño archivo en la carpeta temporal y se envía la próxima vez que la app arranque con la misma clave.

Se capturan como mucho 10 por minuto, y el mismo error una vez cada 10 segundos, para que un bucle que lanza errores no inunde tu proyecto; stats().skippedErrors cuenta los omitidos. Desactívalo todo con captureErrors: false.

Errores que captura tu framework

Los errores que un framework captura por su cuenta nunca llegan a ser no capturados: llama a captureException ahí. En React, desde 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, desde un manejador de errores añadido después de tus rutas:

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

Entornos y plataforma

  • Node: environment es production solo cuando NODE_ENV=production. Cualquier otra cosa, incluida la ausencia de NODE_ENV, es development: define NODE_ENV=production (o environment) en tus servidores. platform es node.
  • Navegador: environment es development en localhost, 127.0.0.1, [::1] o un host .localhost, y production en los demás. platform es web.

Puedes definir cualquiera de los dos en init, por ejemplo Lyrelog.init({ apiKey, environment: "staging" }). Vale cualquier nombre: letras minúsculas, dígitos, - y _, hasta 32.

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

pending guarda los eventos en memoria sin enviarlos, granted los envía y denied lo descarta todo (y, en Node, el archivo de errores no capturados pendientes de envío). El consentimiento no se guarda entre cargas de página: guarda tú la elección de la persona y pásala a init. En el navegador, hasta que se concede el consentimiento, los ids de instalación y de sesión se quedan en memoria, no en localStorage ni en sessionStorage.

Ocultar datos sensibles y filtrar

Un valor se convierte en "[redacted]", en los atributos, en el payload y en todo lo que se convierte en texto, cuando el nombre de su clave, en minúsculas y sin -, _, . ni espacios, es o termina en uno de estos: authorization, cookie, password, passwd, secret, token, apikey, privatekey, credential, credentials, accesskey o signature. Así, X-Api-Key, csrf_token, Set-Cookie y user_token se ocultan; token_count y max_tokens, no. redactKeys sustituye esta lista por tus propios nombres, comparados de la misma forma; una lista vacía desactiva la ocultación. Para añadir nombres a los predeterminados, expande DEFAULT_REDACT_KEYS, que el paquete exporta.

Para modificar o descartar eventos tú mismo, pasa beforeSend. Recibe cada evento después de la ocultación y antes de que entre en la cola, y lo devuelve, cambiado o no, o devuelve null para descartarlo. Los ids, ts y resource no se pueden cambiar, lo que devuelvas se vuelve a ajustar a los límites y, si el hook lanza una excepción, el evento se descarta.

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

Vaciar la cola y detener

En el navegador casi nunca necesitas ninguna de las dos cosas: el temporizador y el envío al ocultarse la página ya se encargan.

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

En Node, cierra el cliente en tu rutina de apagado, para que lo que está en cola salga antes de que termine el proceso:

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

Un script que termina con process.exit() se salta beforeExit y pierde lo que sigue en cola: haz await log.close() antes, como arriba.

En una función serverless (AWS Lambda, funciones de Vercel y Netlify, Cloudflare Workers), el runtime congela o termina la función en cuanto responde, antes de que salte el temporizador. Envía lo pendiente antes de devolver:

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

flush, close y el envío al ocultarse la página respetan un Retry-After que haya pedido el servidor: mientras dure, flush vuelve al instante y los eventos esperan.

log.stats() devuelve { queued, queuedBytes, dropped, delivered, rejected, skippedErrors, disabled }; disabled es true después de un 401 o un 403, o cuando el cliente no tiene clave o endpoint al que enviar.

En desarrollo y en tests

Deja apiKey vacío y el cliente avisa una vez y no envía nada, o pasa consent: "denied" para descartar todos los eventos sin aviso:

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

Eventos verificados

Un evento verificado es uno que no puede haber enviado alguien que haya copiado la clave de ingesta pública de una app o de una página web. Qué demuestra eso, y qué no, se explica en Eventos verificados.

En Node, envía con una clave de servidor, lyr_srv_.... Todos los eventos que envía están verificados (verified_by es server) y no cuentan para la cuota diaria de una dirección. Un propietario la crea en la página API keys del proyecto, Send events from a server, tras un inicio de sesión reciente (en los últimos 10 minutos), y se muestra una sola vez. Es un secreto: mantenla fuera del repositorio y léela del entorno del servidor o de su almacén de secretos.

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

En un navegador la clave es la clave de ingesta pública, así que los eventos de una página llegan sin verificar y cuentan para la cuota diaria. Nunca pongas una clave de servidor en código de navegador: cualquier cosa que haya en la página se puede leer. Para verificar los eventos de un sitio, reenvíalos a través de tu propio servidor: apunta endpoint a una ruta de tu backend que reenvíe cada lote con la clave de servidor. Esa ruta debe aceptar eventos solo de tus propias sesiones con inicio de sesión, o no verifica nada.

Para comprobarlo, abre el explorador: en Filter, elige Verified by y Server key (los otros valores son App Attest y Not verified). Un evento abierto lo indica en Context, en su línea Sender: Verified, server key o Not verified, public key.

Los eventos enviados con una clave de ingesta o con una clave de acceso total, lyr_adm_..., llegan sin verificar: cualquiera que tenga una clave pública podría haber enviado lo mismo. Un evento verificado demuestra quién lo envió, no que lo que dice sea cierto.

Consulta Eventos verificados para saber quién verifica qué y cómo funciona la cuota diaria.

Configuración

OpciónPredeterminadoSignificado
endpointhttps://ingest.lyrelog.comLa URL base; si pegas una ruta /v1/..., se quita. Solo https; http solo en localhost
apiKeyobligatoriaNavegador: la clave de ingesta del proyecto, segura en código de cliente. Node: una clave de servidor, nunca en código de cliente. Sin ella el cliente no envía nada
environmentdetectadoCualquier nombre: letras minúsculas, dígitos, - y _, hasta 32
platformweb / nodeapi, worker...
releaseNode: npm_package_versionSe envía como app_version. El valor predeterminado solo existe al arrancar con un script del paquete: pásalo tú con node server.js, Docker o systemd
appIdWeb: el nombre del host. Node: npm_package_nameSe envía como app_id. En Node, con la misma salvedad que release
minimumLeveldebugLos eventos por debajo se descartan antes de entrar en la cola
flushIntervalMs5000Cada cuánto se envía la cola
maxQueue10000Eventos esperando en memoria; por encima, se van los más antiguos
maxQueueBytes16 MiBEl mismo tope, en bytes
redactKeysDEFAULT_REDACT_KEYSNombres de clave que se ocultan; sustituye a los predeterminados, [] lo desactiva
beforeSendningunoModifica un evento, o devuelve null para descartarlo
consentgrantedgranted, pending o denied
captureErrorstrueCaptura errores no capturados y rechazos no gestionados

Entrega y límites

Cuándo envíaCada 5 s, en cuanto hay 500 eventos esperando, con flush() y con close(). En el navegador, también cuando se oculta la página; en Node, en beforeExit (no en process.exit(); el temporizador nunca mantiene vivo el proceso).
LotesHasta 500 eventos o 512 KiB, NDJSON, gzip (CompressionStream en navegadores, zlib en Node). Un evento de más de 1 MiB se descarta y se cuenta.
ReintentosBackoff con jitter completo (de 1 s, duplicándose hasta 5 min), respetando Retry-After. Un reintento reenvía los mismos eventos con los mismos ids. Cualquier otro 4xx descarta el lote; un 3xx lo descarta con un aviso (no se siguen redirecciones); una clave rechazada detiene los envíos hasta reiniciar y conserva los eventos.
Cuota mensualCuando una organización Free ha agotado los eventos de su mes, el servidor responde 429. Los eventos se quedan en la cola y salen en cuanto el servidor vuelve a aceptarlos, hasta maxQueue. El cliente registra un console.warn con el mensaje del servidor, y solo vuelve a hacerlo después de que se haya aceptado algún lote entretanto.
Sus propios problemasUn endpoint incorrecto, una redirección o un lote descartado: un console.warn que empieza por [lyrelog]. Una clave rechazada y líneas rechazadas: console.debug, así que activa los mensajes detallados en la consola del navegador para verlos.
ContextoWeb: os_name: "web", la familia del navegador como device_model, navigator.language como locale, un id de instalación en localStorage y un id de sesión en sessionStorage (nuevo tras 30 min de inactividad). Node: process.platform, os.release(), la arquitectura de la CPU e ids por proceso. Si el almacenamiento lanza errores (modo privado), se recurre a la memoria.
LímitesSe ajustan antes de entrar en la cola; los atributos sobrantes se cuentan en lyrelog_dropped_attrs, los puntos en los nombres de atributo se convierten en _ y un payload de más de 64 KiB se convierte en un resumen con una vista previa.

Conviene saber:

  • La cola vive en memoria. Los eventos que siguen esperando cuando una pestaña se cierra del todo, o cuando un proceso se mata con SIGKILL o termina con process.exit(), se pierden. Llama a close() en la rutina de apagado de tu servidor y a flush() al final de un handler serverless.
  • Una página que se oculta envía como mucho unos 60 KB; el resto espera a que la página vuelva.
  • En la web, la clave de ingesta es pública. Cualquiera que lea tu página puede enviar eventos también al proyecto, así que no trates los eventos entrantes como datos de confianza. Esos eventos no están verificados; los que llegan desde Node con una clave de servidor, sí.