@fabbahiense/pulsar-next

Next.js SDK para o Pulsar. Funciona com App Router (Next 13+).

Instalacao

npm install @fabbahiense/pulsar-next

Setup

1. instrumentation.ts (raiz do projeto)

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { initPulsar } = await import('@fabbahiense/pulsar-next')
    initPulsar({
      url: process.env.PULSAR_URL!,
      apiKey: process.env.PULSAR_API_KEY!,
      serviceName: 'web',
    })
  }
}

Isso intercepta console.log/info/warn/error automaticamente. Cada log vai pro Pulsar com traceId se estiver dentro de um request handler envolvido pelo withPulsar.

2. Route handlers (opcional, mas recomendado)

import { withPulsar } from '@fabbahiense/pulsar-next'

export const GET = withPulsar(async (req: Request) => {
  console.log('Fetching user')
  return Response.json({ ok: true })
})

Cada request ganha traceId (do header x-trace-id ou auto-gerado). Logs dentro do handler herdam o mesmo traceId. Por padrão emite 1 log automático no fim da request com método/URL/status/duração.

2b. Capturar request/response bodies e headers

export const POST = withPulsar(async (req: Request) => {
  const data = await req.json()
  const result = await processCheckout(data)
  return Response.json(result)
}, {
  captureBody: true,
  captureResponseBody: true,
  maxBodySize: 10240,            // 10KB por body, truncado se maior
  redactKeys: ['cpf', 'cardNumber'],
})

Cada chave redacta recursivamente em bodies e headers. Default redact: password, token, secret, authorization, cookie, api-key.

No painel lateral do Pulsar aparecem as seções Request body, Response body, Request/Response headers, Query e Path params com syntax highlight + copy.

3. Logger estruturado

import { createLogger } from '@fabbahiense/pulsar-next'

const log = createLogger({ serviceName: 'auth' })

log.info('User logged in', { userId: '123' })
log.error('Login failed', { reason: 'invalid_password', userId: '123' })

4. Capturar erros do client (error.tsx)

'use client'
import { initPulsarClient, captureException } from '@fabbahiense/pulsar-next/client'
import { useEffect } from 'react'

initPulsarClient({
  url: process.env.NEXT_PUBLIC_PULSAR_URL!,
  apiKey: process.env.NEXT_PUBLIC_PULSAR_CLIENT_KEY!,
})

export default function Error({ error }: { error: Error }) {
  useEffect(() => {
    captureException(error)
  }, [error])
  return <div>Algo deu errado</div>
}

Variaveis de ambiente

PULSAR_URL=https://seu-pulsar.com
PULSAR_API_KEY=psk_xxx

Pro client component, use prefixo NEXT_PUBLIC_.

Notas

• Edge runtime (middleware.ts) nao tem AsyncLocalStorage — withPulsar so funciona em route handlers Node.
• Serverless (Vercel): chame await flushPulsar() antes do response retornar pra garantir que logs nao se percam.
• Captura de erros server-side: withPulsar ja captura erros que escapam do handler. Pra capturar manualmente, use captureException(err).

License

MIT