JavaScript
Logs estruturados de um site ou de um serviço Node. TypeScript, ESM, sem dependências.
Um único pacote, @lyrelog/js, para navegadores e Node 22.12 ou mais recente. O mesmo import
funciona em todo lugar: os bundlers escolhem o build do navegador e o Node escolhe o build do Node.
O pacote é só ESM: use import, ou require() (o Node 22.12 carrega módulos ES sem flag).
Prévia interna: este pacote ainda não foi publicado. Até lá, pnpm add @lyrelog/js falha:
não existe pacote no npm.
Instalação
pnpm add @lyrelog/jsPrimeiros passos
Lyrelog.init retorna um cliente. Crie um por carregamento de página ou por processo, o mais cedo
possível.
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",
});No navegador, use a chave de ingestão do projeto, lyr_ing_...: ela só consegue adicionar
eventos, então pode ficar numa página sem risco. No Node, use uma chave de servidor, lyr_srv_...:
os eventos dela são verificados e o limite diário de um mesmo endereço de remetente não se aplica a eles.
Nunca coloque uma chave de servidor em código de navegador. Para ter eventos verificados vindos de
uma página, envie-os pelo seu próprio servidor.
Os eventos vão para https://ingest.lyrelog.com. Passe endpoint só para enviá-los a outro
lugar. É a URL base; se você colar um caminho .../v1/events:batch, ele é removido.
Chamar init de novo com o mesmo endpoint e a mesma chave devolve o cliente ativo quando a
configuração é a mesma; caso contrário, fecha esse cliente e inicia um novo, então um hot reload
nunca deixa dois clientes. Sem apiKey, ou com um endpoint que não seja https (http simples só em
localhost), o cliente avisa uma vez no console e não envia nada.
Content Security Policy
Se o seu site define uma Content Security Policy, libere a ingestão em connect-src:
Content-Security-Policy: connect-src 'self' https://ingest.lyrelog.comRegistrar eventos
Um método por nível: 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 } });Uma chamada de log ajusta o evento aos limites do servidor, serializa-o (mudanças posteriores nos
seus objetos não vazam para ele) e o coloca na fila. Entrada inválida vira algo válido, nunca uma
exceção. Depois de close(), as chamadas de log não fazem nada.
Loggers para cada área
const jobs = log.logger("jobs");
jobs.info("job_done", { attrs: { job: "digest", ms: 412 } });Um logger tem todos os métodos de nível e log. Para capturar um erro na área dele, use
log.captureException(error, { category: "jobs" }).
Usuários
log.setUser(accountId); // attached to every following event
log.setUser(null); // on sign-outlog.sessionId dá a sessão atual, por exemplo para uma tela de suporte. O id do usuário não é
salvo: no navegador, chame setUser de novo a cada carregamento de página, assim que souber quem
é a pessoa.
Telas
log.screen("Checkout");Registra screen_viewed na área navigation com a tela anterior e os segundos passados nela, e
todos os eventos seguintes levam screen. Na web, chame-o quando a página mudar. Dê um nome à tela
em vez de passar a URL: /orders/1234 criaria uma tela por pedido.
function OrderPage() {
useEffect(() => log.screen("Order"), []);
// ...
}Requisições
Não há registro automático de requisições. Registre as requisições que importam para você com um nome estável e os campos que quer ver em gráficos, como faz o 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) },
});Exceções
try {
await pay();
} catch (error) {
log.captureException(error, { category: "checkout", attrs: { step: "pay" } });
}Registra exception (nível error, ou level se você passar um) com error_type e
error_message como atributos, e o nome, a mensagem, a stack, code e até três causes no
payload. Qualquer coisa lançada funciona, não só Error. De um valor lançado que não é um Error,
só name, message, code e status são mantidos, nunca o resto do objeto (o erro de um cliente
HTTP traria os headers da requisição). No navegador, as URLs nas stacks perdem a query string e o
fragmento.
Erros não capturados
Eles são capturados para você, como o mesmo evento exception com handled: false e um
mechanism:
- No navegador, erros que chegam a
window(onerror) e promises rejeitadas sem handler (onunhandledrejection). O console continua mostrando esses erros. O opaco "Script error." de outra origem não traz nada útil e é ignorado. - No Node, uma exceção ou rejeição não capturada. O Lyrelog só observa (usa
uncaughtExceptionMonitor), então o processo continua dando crash como daria sem ele. Não há tempo para enviar antes de ele sair, então o evento é gravado num pequeno arquivo na pasta temporária e enviado na próxima vez que o app iniciar com a mesma chave.
São capturados no máximo 10 por minuto, e o mesmo erro uma vez a cada 10 segundos, então um loop
que lança exceções não consegue inundar o seu projeto; stats().skippedErrors conta o que foi
ignorado. Desligue tudo isso com captureErrors: false.
Erros que o seu framework captura
Erros que um framework captura por conta própria nunca chegam a ser não capturados: chame
captureException ali. No React, a partir de um 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;
}
}No Express, a partir de um error handler, adicionado depois das suas rotas:
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);
});Ambientes e plataforma
- Node:
environmentéproductionsó quandoNODE_ENV=production. Qualquer outro valor, inclusive a ausência deNODE_ENV, édevelopment: definaNODE_ENV=production(ouenvironment) nos seus servidores.platforménode. - Navegador:
environmentédevelopmentemlocalhost,127.0.0.1,[::1]ou num host.localhost; caso contrário,production.platforméweb.
Defina qualquer um dos dois em init, por exemplo Lyrelog.init({ apiKey, environment: "staging" }).
Qualquer nome serve: letras minúsculas, dígitos, - e _, até 32.
Consentimento
const log = Lyrelog.init({ apiKey, consent: "pending" });
// later
log.setConsent("granted"); // or "denied"pending mantém os eventos em memória sem enviar, granted os envia, denied descarta tudo (e,
no Node, o arquivo de erros não capturados esperando envio).
O consentimento não é salvo entre carregamentos de página: guarde você mesmo a escolha da pessoa e
passe-a para init. No navegador, até o consentimento ser dado, os ids de instalação e de sessão
ficam em memória, não em localStorage nem em sessionStorage.
Ocultar e filtrar
Um valor vira "[redacted]", nos atributos, no payload e em tudo o que for convertido em string,
quando o nome da chave dele, em minúsculas e sem -, _, . ou espaços, é ou termina com um de
authorization, cookie, password, passwd, secret, token, apikey, privatekey,
credential, credentials, accesskey ou signature. Assim, X-Api-Key, csrf_token,
Set-Cookie e user_token são ocultados; token_count e max_tokens não. redactKeys
substitui essa lista pelos seus próprios nomes, comparados da mesma forma; uma lista vazia desliga
a ocultação. Para somar aos padrões, espalhe DEFAULT_REDACT_KEYS, que o pacote exporta.
Para alterar ou descartar eventos você mesmo, passe beforeSend. Ele recebe cada evento depois da
ocultação e antes de entrar na fila, e o retorna, alterado ou não, ou null para descartá-lo. Os
ids, ts e resource não podem ser alterados, o que você retorna é ajustado aos limites de novo,
e um hook que lança exceção descarta o evento.
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;
},
});Esvaziar a fila e parar
No navegador, você raramente precisa de qualquer um dos dois: o timer e a página ficando oculta já enviam.
await log.flush(); // send what is queued nowNo Node, feche o cliente no seu caminho de desligamento, para que o que está na fila saia antes de o processo terminar:
process.on("SIGTERM", async () => {
await log.close(); // sends what is queued, then stops
process.exit(0);
});Um script que termina com process.exit() pula beforeExit e perde o que ainda está na fila:
faça await log.close() antes, como acima.
Numa função serverless (AWS Lambda, funções da Vercel e da Netlify, Cloudflare Workers), o runtime congela ou encerra a função assim que ela responde, antes de o timer disparar. Esvazie a fila antes de retornar:
export async function handler(event) {
log.info("order_created", { attrs: { order_id: event.id } });
await log.flush();
return { statusCode: 200 };
}flush, close e o envio quando a página fica oculta respeitam um Retry-After pedido pelo
servidor: durante ele, flush retorna na hora e os eventos esperam.
log.stats() retorna { queued, queuedBytes, dropped, delivered, rejected, skippedErrors, disabled };
disabled é true depois de um 401 ou 403, ou quando o cliente não tem chave ou endpoint para
onde enviar.
Em desenvolvimento e testes
Deixe apiKey vazio e o cliente avisa uma vez e não envia nada, ou passe consent: "denied" para
descartar todos os eventos sem aviso:
const log = Lyrelog.init({
apiKey: process.env.LYRELOG_KEY ?? "",
consent: process.env.NODE_ENV === "test" ? "denied" : "granted",
});Eventos verificados
Um evento verificado é um evento que não pode ter sido enviado por alguém que copiou a chave de ingestão pública de um app ou de uma página web. O que isso prova, e o que não prova, está em Eventos verificados.
No Node, envie com uma chave de servidor, lyr_srv_.... Todo evento que ela envia é verificado
(verified_by é server) e não conta para a
cota diária de um endereço. Um
proprietário a cria na página API keys do projeto, em Send events from a server, depois de
ter entrado recentemente (nos últimos 10 minutos), e ela é mostrada uma única vez. É um segredo:
mantenha-a fora do repositório e leia-a do ambiente do servidor ou do seu gerenciador de segredos.
export const log = Lyrelog.init({
apiKey: process.env.LYRELOG_KEY!, // lyr_srv_..., set in the server's environment
});Num navegador, a chave é a chave de ingestão pública, então os eventos de uma página chegam não
verificados e contam para a cota diária. Nunca coloque uma chave de servidor em código de
navegador: qualquer coisa na página pode ser lida. Para verificar os eventos de um site,
repasse-os pelo seu próprio servidor:
aponte endpoint para uma rota no seu backend que encaminhe cada lote com a chave de servidor.
Essa rota deve aceitar eventos só das suas próprias sessões autenticadas, senão não verifica nada.
Para conferir, abra o explorer: em Filter, escolha Verified by e Server key (os outros valores são App Attest e Not verified). Um evento aberto mostra isso em Context, na linha Sender: Verified, server key ou Not verified, public key.
Eventos enviados com uma chave de ingestão ou com uma chave de acesso total, lyr_adm_..., chegam
não verificados: qualquer pessoa com uma chave pública poderia ter enviado o mesmo. Um evento
verificado prova quem o enviou, não que o que ele diz seja verdade.
Veja Eventos verificados para saber quem verifica o quê e como funciona a cota diária.
Configuração
| Opção | Padrão | Significado |
|---|---|---|
endpoint | https://ingest.lyrelog.com | A URL base; um caminho /v1/... colado é removido. Só https, http só em localhost |
apiKey | obrigatório | Navegador: a chave de ingestão do projeto, segura em código cliente. Node: uma chave de servidor, nunca em código cliente. Sem ela, o cliente não envia nada |
environment | detectado | Qualquer nome: letras minúsculas, dígitos, - e _, até 32 |
platform | web / node | api, worker... |
release | Node: npm_package_version | Enviado como app_version. O padrão só existe quando o processo é iniciado por um script do pacote: passe-o você mesmo com node server.js, Docker ou systemd |
appId | Web: o nome do host. Node: npm_package_name | Enviado como app_id. No Node, a mesma ressalva de release |
minimumLevel | debug | Eventos abaixo dele são descartados antes de entrar na fila |
flushIntervalMs | 5000 | Com que frequência a fila é enviada |
maxQueue | 10000 | Eventos esperando em memória; além disso, os mais antigos saem |
maxQueueBytes | 16 MiB | O mesmo limite, em bytes |
redactKeys | DEFAULT_REDACT_KEYS | Nomes de chave a ocultar; substitui os padrões, [] desliga |
beforeSend | nenhum | Altera um evento, ou retorna null para descartá-lo |
consent | granted | granted, pending ou denied |
captureErrors | true | Captura erros não capturados e rejeições sem handler |
Entrega e limites
| Quando envia | A cada 5 s, assim que 500 eventos estão esperando, em flush() e close(). No navegador, também quando a página fica oculta; no Node, em beforeExit (não em process.exit(); o timer nunca mantém o processo vivo). |
| Lotes | Até 500 eventos ou 512 KiB, NDJSON, gzip (CompressionStream nos navegadores, zlib no Node). Um evento acima de 1 MiB é descartado e contado. |
| Novas tentativas | Backoff com full jitter (1 s, dobrando até 5 min), respeitando Retry-After. Uma nova tentativa reenvia os mesmos eventos com os mesmos ids. Qualquer outro 4xx descarta o lote; um 3xx o descarta com um aviso (redirecionamentos não são seguidos); uma chave recusada interrompe os envios até reiniciar e mantém os eventos. |
| Cota mensal | Quando uma organização Free já usou os eventos do mês, o servidor responde 429. Os eventos ficam na fila e saem quando o servidor voltar a aceitá-los, até maxQueue. O cliente registra um console.warn com a mensagem do servidor, e de novo só depois de um lote ter sido aceito nesse meio-tempo. |
| Problemas do próprio SDK | Um endpoint errado, um redirecionamento ou um lote descartado: um console.warn começando com [lyrelog]. Uma chave recusada e linhas rejeitadas: console.debug, então ative as mensagens detalhadas (verbose) no console do navegador para vê-las. |
| Contexto | Web: os_name: "web", a família do navegador como device_model, navigator.language como locale, um id de instalação em localStorage e um id de sessão em sessionStorage (novo depois de 30 min inativo). Node: process.platform, os.release(), a arquitetura da CPU e ids por processo. Um armazenamento que lança exceção (modo privado) passa a usar a memória. |
| Limites | Ajustados antes de entrar na fila; atributos extras são contados em lyrelog_dropped_attrs, pontos nos nomes de atributos viram _, um payload acima de 64 KiB vira um resumo com uma prévia. |
Vale saber:
- A fila fica em memória. Eventos ainda esperando quando uma aba é fechada de vez, ou quando um
processo é morto com
SIGKILLou termina comprocess.exit(), são perdidos. Chameclose()no caminho de desligamento do seu servidor, eflush()no fim de um handler serverless. - Uma página ficando oculta envia no máximo uns 60 KB; o resto espera a página voltar.
- Na web, a chave de ingestão é pública. Qualquer pessoa que leia a sua página também pode enviar eventos para o projeto, então não trate os eventos recebidos como entrada confiável. Esses eventos não são verificados; os do Node com uma chave de servidor são.