Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

JavaScript

Logs estruturados de um site ou de um serviço Node. TypeScript, ESM, sem dependências.

Navegadores e Node

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/js

Primeiros 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.com

Registrar 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-out

log.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 é production só quando NODE_ENV=production. Qualquer outro valor, inclusive a ausência de NODE_ENV, é development: defina NODE_ENV=production (ou environment) nos seus servidores. platform é node.
  • Navegador: environment é development em localhost, 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.

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 now

No 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çãoPadrãoSignificado
endpointhttps://ingest.lyrelog.comA URL base; um caminho /v1/... colado é removido. Só https, http só em localhost
apiKeyobrigatórioNavegador: 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
environmentdetectadoQualquer nome: letras minúsculas, dígitos, - e _, até 32
platformweb / nodeapi, worker...
releaseNode: npm_package_versionEnviado 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
appIdWeb: o nome do host. Node: npm_package_nameEnviado como app_id. No Node, a mesma ressalva de release
minimumLeveldebugEventos abaixo dele são descartados antes de entrar na fila
flushIntervalMs5000Com que frequência a fila é enviada
maxQueue10000Eventos esperando em memória; além disso, os mais antigos saem
maxQueueBytes16 MiBO mesmo limite, em bytes
redactKeysDEFAULT_REDACT_KEYSNomes de chave a ocultar; substitui os padrões, [] desliga
beforeSendnenhumAltera um evento, ou retorna null para descartá-lo
consentgrantedgranted, pending ou denied
captureErrorstrueCaptura erros não capturados e rejeições sem handler

Entrega e limites

Quando enviaA 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).
LotesAté 500 eventos ou 512 KiB, NDJSON, gzip (CompressionStream nos navegadores, zlib no Node). Um evento acima de 1 MiB é descartado e contado.
Novas tentativasBackoff 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 mensalQuando 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 SDKUm 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.
ContextoWeb: 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.
LimitesAjustados 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 SIGKILL ou termina com process.exit(), são perdidos. Chame close() no caminho de desligamento do seu servidor, e flush() 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.