Node.js

Instalar npm install @blipit/node

O @blipit/node captura exceções não capturadas e rejeições de promise não tratadas por conta própria, adiciona handlers para Express e Fastify, e envia logs e tentativas de login com a mesma chave. Use a chave secreta; ela fica no servidor. A partir da 0.3 tem também configuração numa linha para Koa, Hono e NestJS, e um wrapper para handlers ao estilo AWS Lambda.

Cole-o no Claude Code, no Cursor ou em qualquer assistente de programação com IA. Inclui os passos e o código. Em app.blipit.io, em Chaves de API, o mesmo prompt já vem com a sua chave preenchida.
Vídeo: instalar o Blipit em qualquer stack, a partir de 1:07

1Instalar

sh
npm install @blipit/node

2Obtenha suas chaves

Entre no app.blipit.io e abra Chaves de API na barra lateral, depois o seu projeto. Cada projeto tem duas chaves. A chave pública começa com blipit_pk_: ela vai no código do navegador e do app, só pode enviar eventos e é segura para qualquer pessoa ver. A chave secreta começa com blipit_sk_: ela fica no seu servidor ou no Odoo, nunca em um navegador, porque também pode ler e alterar problemas. A chave secreta é exibida uma única vez, logo depois de criada, então copie-a nesse momento; se você a perder, clique em Criar uma nova chave secreta, e a antiga para de funcionar na hora. Alguns SDKs também precisam do id do projeto, exibido na mesma página.

Chaves de API no app.blipit.io: a chave pública (blipit_pk_) para código de navegador e a chave secreta (blipit_sk_) para servidores e o Odoo.
Chaves de API no app.blipit.io: a chave pública (blipit_pk_) para código de navegador e a chave secreta (blipit_sk_) para servidores e o Odoo.
Uma nova chave secreta é exibida uma única vez. Copie-a agora: ela é armazenada com hash e não pode ser exibida novamente.
Uma nova chave secreta é exibida uma única vez. Copie-a agora: ela é armazenada com hash e não pode ser exibida novamente.

3Mantenha a chave no ambiente

O Node usa a chave secreta. Coloque-a em uma variável de ambiente, nunca no código: localmente em um arquivo .env que o Node 20.6 ou posterior carrega com --env-file, e em produção no ambiente ou nas configurações de segredos do seu host (Fly secrets, Docker, systemd, Render, Vercel). Reinicie o processo depois de alterá-la.

.env
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key
sh
node --env-file=.env --import ./instrument.mjs server.mjs

4Mantenha as chaves fora do git

Mantenha as chaves em variáveis de ambiente ou nas configurações de segredos do seu host, nunca em código que você faz commit, e adicione seus arquivos .env ao .gitignore. Uma chave pública em uma página web é normal. Se uma chave secreta for parar no git, em uma página pública, em uma captura de tela ou em um chat, abra Chaves de API, clique em Criar uma nova chave secreta e cole a nova chave onde a antiga era usada: a chave antiga para de funcionar na hora.

.gitignore
.env
.env.local
.env.*.local

5Inicialize primeiro

Coloque isto em um arquivo que rode antes do seu app, e importe-o primeiro.

instrument.mjs
import * as Blipit from "@blipit/node";

Blipit.init({
  key: process.env.BLIPIT_SECRET_KEY,
  environment: process.env.NODE_ENV,
  release: process.env.RELEASE,
  serverName: "api",
});

6Express, Fastify, Koa, Hono ou NestJS

Adicione o handler depois das suas rotas para que erros tratados e não tratados cheguem ao Blipit, com o método, a URL e o user agent da requisição. Koa, Hono e NestJS precisam de uma linha cada: o middleware do Koa vem primeiro, o do Hono antes das rotas. Reportam erros com estado 500 ou superior. Os pedidos aparecem então na página Pulse por rota, como GET /users/:id, em vez de uma linha por URL.

js
import "./instrument.mjs";
import * as Blipit from "@blipit/node";
import express from "express";

const app = express();
app.get("/", (req, res) => res.send("ok"));
app.use(Blipit.expressErrorHandler());
app.listen(3000);
Fastify
await app.register(Blipit.fastifyPlugin());
Koa
app.use(Blipit.koaMiddleware());
Hono
app.use(Blipit.honoMiddleware());
NestJS
app.useGlobalInterceptors(Blipit.nestInterceptor());

7Serverless: AWS Lambda e Vercel

Os hosts serverless pausam a função assim que ela responde, e o Lambda não executa o servidor HTTP do Node, por isso envolva o handler. wrapHandler regista o pedido (eventos de API Gateway, URL de função e load balancer por método e rota, outros eventos pelo nome da função), reporta erros e envia tudo antes de o handler devolver; só espera quando há algo para enviar, no máximo 2 segundos. traceRequest faz o mesmo para qualquer handler que receba um Request. Na Vercel os dados saem depois da resposta através de waitUntil, por isso nada é atrasado. No Next.js use withBlipit (veja o guia do Next.js).

js
import * as Blipit from "@blipit/node";

export const handler = Blipit.wrapHandler(async (event, context) => {
  return { statusCode: 200, body: "ok" };
});
traceRequest
export default { fetch: (request) => Blipit.traceRequest(request, () => app.fetch(request)) };

8Captura manual, logs e tentativas de login

js
Blipit.captureException(err);
Blipit.captureMessage("cache miss rate above 50%", "warning");
Blipit.setUser({ id: "user-42" });
Blipit.log.info("order placed", { order_id: 42 });
Blipit.captureSecurity({ kind: "login_failed", actor: email, ip, userAgent, outcome: "bad_password" });
await Blipit.flush();

9Dependências e saúde do servidor

A partir da 0.2, o SDK também regista as suas chamadas à base de dados e a serviços externos, e o CPU, memória e event loop do servidor. Veja os guias Dependências e Saúde do servidor; controla-se com tracesSampleRate, tracing: false e metrics: false.

10Confira se funciona

Abra Problemas em app.blipit.io. O primeiro evento aparece em alguns segundos, agrupado em um problema, e os responsáveis recebem um e-mail.

js
Blipit.captureMessage("Hello from Node");

Bom saber

  • Em uma exceção não capturada, o SDK envia os eventos pendentes e depois encerra com código 1; sobrescreva com onFatal.
  • captureConsole: true transforma console.log e afins em linhas de log enviadas à página de Logs.
  • Confira a versão instalada com npm ls @blipit/node (ou pnpm list @blipit/node). O pnpm 11 espera um dia antes de instalar uma versão nova (minimum-release-age), então no dia do lançamento o pnpm add instala a versão anterior sem avisar; para pegar a nova na hora, rode pnpm add @blipit/node@<version> --config.minimum-release-age=0.
  • Manter o Blipit atualizado: o guia Manter o Blipit atualizado (docs.blipit.io/updates) explica o banner de atualização, os e-mails de versões importantes, o aviso no seu console de desenvolvimento e o comando de atualização para esta plataforma.
  • Um projeto por app e plataforma: cada projeto escolhe a sua plataforma quando é criado (Android, iOS, React Native, Flutter, Web, Backend ou Odoo), e o Blipit recusa com um erro claro os dados de qualquer outra plataforma, por isso uma app iOS e uma app Android precisam de dois projetos com duas chaves. Releases, versões, taxas de falhas e builds das lojas são diferentes em cada plataforma, e misturá-los num projeto torna todos errados. Um projeto Web também aceita o lado servidor da mesma app web (o servidor Next.js ou Node), e um projeto React Native ou Flutter também aceita os seus próprios relatórios de falhas nativos de Android e iOS.

Travou? Envie um e-mail para support@blipit.io. As chaves e o id de cada projeto ficam em Chaves de API no app.blipit.io.