traza-log 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# traza
+
+SDK ligero de tracing y logging para Node, navegador y edge runtimes. Envía eventos y spans al dashboard de **Traza** sin bloquear el flujo principal de tu aplicación.
+
+- `traza.log / info / warn / error / debug` — drop-in replacement de `console`.
+- `traza.startSpan`, `traza.time`, `traza.instrument` — mide latencia de queries, peticiones HTTP, o cualquier bloque async.
+- `traza.middleware()` — instrumenta cada request HTTP automáticamente.
+- Cola en memoria + batching HTTP + reintentos con backoff: **nunca bloquea**, descarta antes que retrasar.
+- Compatible con Node 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, navegadores modernos, React Native / Capacitor / Ionic.
+
+## Instalación
+
+```bash
+pnpm add traza      # o npm i traza / yarn add traza / bun add traza
+```
+
+## Configuración
+
+Solo necesitas el token. El endpoint por defecto es **`https://traza.gd.pe`** — pásalo explícitamente solo si self-hosteas.
+
+```ts
+import { traza } from 'traza'
+
+traza.configure({
+  token: process.env.TRAZA_TOKEN!,           // generado en el dashboard
+  service: 'api',                            // opcional
+  environment: process.env.NODE_ENV,         // opcional
+  release: process.env.GIT_SHA,              // opcional
+  defaultAttributes: { region: 'lima' },     // se adjunta a todo evento
+  // endpoint: 'https://tu-traza.miempresa.com',  // solo si self-hosteas
+  flushIntervalMs: 3000,                     // default
+  maxBatchSize: 100,                         // default
+  maxQueueSize: 10000,                       // default
+  sampleRate: 1,                             // 0..1
+  forwardToConsole: true,                    // imprime también en consola local
+})
+```
+
+## Logs
+
+```ts
+traza.log('Hola mundo')
+traza.info('usuario autenticado', { userId: 42 })
+traza.warn('consulta lenta', { ms: 1200 })
+traza.error('fallo en checkout', { err })
+traza.debug('cache miss', { key: 'user:42' })
+```
+
+## Medir rendimiento
+
+Tres formas, elige la que te quede más natural:
+
+### 1. Span manual
+
+```ts
+const span = traza.startSpan('db.query', { attributes: { table: 'users' } })
+try {
+  const rows = await db.select().from(users)
+  span.setAttribute('rowCount', rows.length)
+  span.end({ status: 'ok' })
+} catch (err) {
+  span.end({ status: 'error', error: err })
+}
+```
+
+### 2. `time()` — wrap automático
+
+```ts
+const users = await traza.time('db.users', () => db.select().from(usersTable))
+```
+
+### 3. `instrument()` — para funciones reutilizables
+
+```ts
+const getUser = traza.instrument(
+  'db.getUser',
+  async (id: string) => db.query.users.findFirst({ where: eq(users.id, id) }),
+  (id) => ({ userId: id }),
+)
+```
+
+## Middleware HTTP
+
+### Express / Connect / Polka
+
+```ts
+import express from 'express'
+import { traza } from 'traza'
+
+const app = express()
+app.use(traza.middleware())
+```
+
+### Nuxt 3 / Nitro / H3
+
+```ts
+// server/middleware/traza.ts
+import { traza } from 'traza'
+
+export default defineEventHandler((event) => {
+  return traza.h3((e) => e)(event)
+})
+```
+
+Cada request HTTP genera una span con `http.method`, `http.url`, `http.status_code` y propaga el `traceId` a todos los logs y spans hijos.
+
+## Contexto
+
+```ts
+traza.runWithContext({ attributes: { requestId } }, async () => {
+  traza.info('start')          // incluye requestId
+  await traza.time('work', work)
+})
+```
+
+## Comportamiento no bloqueante
+
+- Los eventos se acumulan en una cola en memoria (max 10 000 por defecto).
+- Se envían al dashboard cada `flushIntervalMs` o cuando la cola alcanza `maxBatchSize`.
+- Si la red falla: reintentos con backoff exponencial (200 ms → 5 s, 3 intentos).
+- Si la cola se llena: se descartan los eventos **más antiguos**, el código de aplicación nunca espera.
+- Hooks de shutdown (`beforeExit` en Node, `pagehide` en navegador) hacen flush final.
+
+## Apagar limpiamente
+
+```ts
+process.on('SIGTERM', async () => {
+  await traza.shutdown()
+  process.exit(0)
+})
+```
+
+## Licencia
+
+MIT.