JavaScript
Logs estructurados desde un sitio web o un servicio Node. TypeScript, ESM, sin dependencias.
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/jsPrimeros 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.comRegistrar 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-outlog.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:
environmentesproductionsolo cuandoNODE_ENV=production. Cualquier otra cosa, incluida la ausencia deNODE_ENV, esdevelopment: defineNODE_ENV=production(oenvironment) en tus servidores.platformesnode. - Navegador:
environmentesdevelopmentenlocalhost,127.0.0.1,[::1]o un host.localhost, yproductionen los demás.platformesweb.
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.
Consentimiento
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 nowEn 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ón | Predeterminado | Significado |
|---|---|---|
endpoint | https://ingest.lyrelog.com | La URL base; si pegas una ruta /v1/..., se quita. Solo https; http solo en localhost |
apiKey | obligatoria | Navegador: 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 |
environment | detectado | Cualquier nombre: letras minúsculas, dígitos, - y _, hasta 32 |
platform | web / node | api, worker... |
release | Node: npm_package_version | Se 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 |
appId | Web: el nombre del host. Node: npm_package_name | Se envía como app_id. En Node, con la misma salvedad que release |
minimumLevel | debug | Los eventos por debajo se descartan antes de entrar en la cola |
flushIntervalMs | 5000 | Cada cuánto se envía la cola |
maxQueue | 10000 | Eventos esperando en memoria; por encima, se van los más antiguos |
maxQueueBytes | 16 MiB | El mismo tope, en bytes |
redactKeys | DEFAULT_REDACT_KEYS | Nombres de clave que se ocultan; sustituye a los predeterminados, [] lo desactiva |
beforeSend | ninguno | Modifica un evento, o devuelve null para descartarlo |
consent | granted | granted, pending o denied |
captureErrors | true | Captura errores no capturados y rechazos no gestionados |
Entrega y límites
| Cuándo envía | Cada 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). |
| Lotes | Hasta 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. |
| Reintentos | Backoff 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 mensual | Cuando 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 problemas | Un 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. |
| Contexto | Web: 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ímites | Se 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
SIGKILLo termina conprocess.exit(), se pierden. Llama aclose()en la rutina de apagado de tu servidor y aflush()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í.