@hemia/trace-manager 0.0.2 → 0.0.3

package/README.md

@@ -1,116 +1,370 @@
 # @hemia/trace-manager
 
-Sistema de gestión de trazabilidad para aplicaciones Node.js. Permite registrar eventos, errores y transacciones utilizando un repositorio NoSQL, con soporte para decoradores automáticos de traza (`@Traceable`) y segmentación por `traceId`, `checkpoint`, `functionCode` y `tags`.
+Sistema de trazabilidad distribuida basado en **OpenTelemetry** para aplicaciones Node.js. Proporciona decoradores automáticos, logging contextual correlacionado con trazas y compatibilidad con ClickHouse para análisis de observabilidad.
 
 ---
 
-## Instalación
+## 🚀 Características
+
+- ✅ **Decorador `@Trace`** - Instrumentación automática de métodos con captura de inputs/outputs
+- ✅ **AsyncLocalStorage** - Propagación automática de contexto sin pasar parámetros manualmente
+- ✅ **Logger Contextual** - Logs automáticamente correlacionados con `traceId` y `spanId`
+- ✅ **Formato OpenTelemetry** - Compatible con estándares de observabilidad
+- ✅ **ClickHouse Ready** - Esquema optimizado para análisis en ClickHouse
+- ✅ **Captura de Errores** - Excepciones registradas como eventos en spans
+- ✅ **Jerarquía de Spans** - Parent-Child spans automáticos por nivel de invocación
+
+---
+
+## 📦 Instalación
 
 ```bash
-npm install @hemia/trace-manager
+npm install @hemia/trace-manager @hemia/app-context
 ```
 
 ---
 
-## Componentes principales
+## 🎯 Componentes principales
+
+### ✅ Decorador `@Trace()`
+
+Instrumenta automáticamente métodos creando spans de OpenTelemetry con captura de inputs, outputs y errores.
+
+#### **Características:**
+
+- 🔹 Crea span automáticamente con `SpanId` único
+- 🔹 Captura argumentos de entrada en `SpanAttributes.app.method.args`
+- 🔹 Captura resultado de retorno en `SpanAttributes.app.method.result`
+- 🔹 Registra excepciones como eventos (`EventsNested`)
+- 🔹 Calcula duración en nanosegundos (`DurationUInt64`)
+- 🔹 Propaga contexto automáticamente a métodos hijos
+
+#### **Uso básico:**
 
-### ✅ `TraceManager<T>`
+```ts
+import { Trace } from '@hemia/trace-manager';
+
+class UserService {
+  @Trace()
+  async createUser(userData: any) {
+    // El decorador captura automáticamente:
+    // - Input: userData
+    // - Output: usuario creado
+    // - Duración de ejecución
+    // - Excepciones si ocurren
+    
+    const user = await this.repository.save(userData);
+    return user;
+  }
 
-Clase encargada de registrar y consultar trazas desde un repositorio MongoDB usando `NoSQLRepository`.
+  @Trace({ name: 'validate-user-email' })
+  private async validateEmail(email: string) {
+    // Span hijo automático (hereda ParentSpanId)
+    return await this.emailValidator.check(email);
+  }
+}
+```
 
-#### Métodos disponibles:
+#### **Opciones de configuración:**
 
-* `save(traceId, additionalData?)`: Guarda una traza
-* `find(filter, options?)`: Busca múltiples trazas
-* `findOne(filter)`: Busca una traza específica
-* `getById(id)`: Obtiene una traza por ID
-* `update(filter, data)`: Actualiza una traza
-* `delete(filter)`: Elimina una traza
-* `aggregate(pipeline)`: Ejecuta una agregación personalizada
+```ts
+interface TraceOptions {
+  name?: string;                    // Nombre personalizado del span (default: ClassName.methodName)
+  kind?: 'SPAN_KIND_INTERNAL'       // Tipo de span: INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER
+       | 'SPAN_KIND_SERVER' 
+       | 'SPAN_KIND_CLIENT'
+       | 'SPAN_KIND_PRODUCER'
+       | 'SPAN_KIND_CONSUMER';
+  attributes?: Record<string, string>; // Atributos personalizados
+}
+```
 
-#### Ejemplo:
+#### **Ejemplo avanzado:**
 
 ```ts
-const manager = new TraceManager<TraceDocument>(traceRepo);
-await manager.save('trace-id-123', { message: 'Evento recibido' });
+class PaymentService {
+  @Trace({ 
+    name: 'process-payment-stripe',
+    kind: 'SPAN_KIND_CLIENT',
+    attributes: { 'payment.provider': 'stripe' }
+  })
+  async processPayment(amount: number, currency: string) {
+    // Span con atributos personalizados
+    return await this.stripeClient.charge(amount, currency);
+  }
+}
 ```
 
 ---
 
-### ✅ Decorador `@Traceable()`
+### ✅ Logger Contextual
 
-Permite trazar automáticamente métodos con input/output y errores.
+Logger que automáticamente correlaciona logs con el `traceId` y `spanId` activo, permitiendo rastrear logs específicos dentro de una traza distribuida.
 
-#### Uso:
+#### **Características:**
 
-```ts
-import { Traceable } from '@hemia/trace-manager';
+- 🔹 Correlación automática con `TraceId` y `SpanId`
+- 🔹 Niveles de severidad: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
+- 🔹 Atributos personalizados en cada log
+- 🔹 Compatible con formato OpenTelemetry para ClickHouse
+
+#### **Uso:**
 
-class MiServicio {
-  @Traceable({ ck: 'MiServicio', fn: 'procesar' })
-  async procesar(data: any) {
-    // lógica
-    return { ok: true };
+```ts
+import { logger } from '@hemia/trace-manager';
+
+class OrderService {
+  @Trace()
+  async placeOrder(order: Order) {
+    logger.info('Processing order', { orderId: order.id, amount: order.total });
+    
+    try {
+      const result = await this.payment.charge(order.total);
+      logger.info('Payment successful', { transactionId: result.id });
+      return result;
+    } catch (error) {
+      logger.error('Payment failed', { error: error.message });
+      throw error;
+    }
   }
 }
 ```
 
-* Input se traza al inicio
-* Output se traza al finalizar
-* Error se traza si ocurre una excepción
+#### **Métodos disponibles:**
+
+```ts
+logger.debug(message: string, attributes?: Record<string, any>): void
+logger.info(message: string, attributes?: Record<string, any>): void
+logger.warn(message: string, attributes?: Record<string, any>): void
+logger.error(message: string, attributes?: Record<string, any>): void
+logger.fatal(message: string, attributes?: Record<string, any>): void
+```
+
+---
+
+## 🏗️ Estructura de Datos
+
+### **TraceSpan** (Span de OpenTelemetry)
+
+Mapea directamente con la tabla `otel_traces` de ClickHouse:
+
+```ts
+interface TraceSpan {
+  Timestamp: string;               // ISO 8601 - DateTime64(9)
+  TraceId: string;                 // ID único de la traza
+  SpanId: string;                  // ID único del span
+  ParentSpanId: string;            // ID del span padre (jerarquía)
+  TraceState: string;              // Estado de propagación W3C
+  ServiceName: string;             // Nombre del servicio
+  SpanName: string;                // Ej: "UserService.createUser"
+  SpanKind: 'SPAN_KIND_INTERNAL' | 'SPAN_KIND_SERVER' | 'SPAN_KIND_CLIENT' | ...;
+  DurationUInt64: bigint;          // Duración en nanosegundos
+  StatusCode: 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR' | 'STATUS_CODE_UNSET';
+  StatusMessage: string;
+  SpanAttributes: Record<string, string>;        // app.method.args, app.method.result, etc.
+  ResourceAttributes: Record<string, string>;    // host.name, service.name, etc.
+  EventsNested: SpanEvent[];       // Excepciones, logs puntuales
+  LinksNested: SpanLink[];         // Enlaces a otras trazas
+}
+```
+
+### **TraceLog** (Log de OpenTelemetry)
+
+Mapea directamente con la tabla `otel_logs` de ClickHouse:
+
+```ts
+interface TraceLog {
+  Timestamp: string;               // ISO 8601
+  TraceId: string;                 // Correlación automática con span activo
+  SpanId: string;                  // Span donde ocurrió el log
+  TraceFlags: number;              // 1 = sampled
+  SeverityText: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+  SeverityNumber: number;          // 5, 9, 13, 17, 21
+  ServiceName: string;
+  Body: string;                    // Mensaje del log
+  LogAttributes: Record<string, string>;         // Atributos custom
+  ResourceAttributes: Record<string, string>;    // Metadata del servicio
+}
+```
 
 ---
 
-### ✅ `addTrace()` y `endTrace()`
+## 🔗 Integración con `@hemia/app-context`
+
+Este paquete utiliza `AsyncLocalStorage` a través de `@hemia/app-context` para mantener el contexto de trazabilidad sin necesidad de pasarlo explícitamente como parámetro.
 
-Funciones internas para agregar nodos de traza al contexto.
+### **Requisitos:**
+
+El contexto debe ser inicializado previamente usando `@hemia/app-context` (generalmente en un middleware HTTP):
 
 ```ts
-const spanId = addTrace('Login', 'authUser', 'input', { email }, 'Inicio de login');
-// lógica
-endTrace(spanId, true, { userId });
+import { asyncContext } from '@hemia/app-context';
+
+// En tu middleware o inicialización
+const context = {
+  traceId: generateTraceId(),
+  spanId: generateSpanId(),
+  serviceName: 'user-service',
+  traceContext: {
+    resourceAttributes: {
+      'service.name': 'user-service',
+      'host.name': os.hostname(),
+    },
+    spans: [],
+    logs: []
+  }
+};
+
+await asyncContext.run(context, async () => {
+  // Todo el código dentro hereda este contexto automáticamente
+  await handleRequest(req, res);
+});
+```
+
+---
+
+## 📊 Esquema ClickHouse
+
+### Tabla: `otel_traces`
+
+```sql
+CREATE TABLE otel_traces (
+    Timestamp DateTime64(9) CODEC(Delta, ZSTD(1)),
+    TraceId String CODEC(ZSTD(1)),
+    SpanId String CODEC(ZSTD(1)),
+    ParentSpanId String CODEC(ZSTD(1)),
+    ServiceName LowCardinality(String) CODEC(ZSTD(1)),
+    SpanName LowCardinality(String) CODEC(ZSTD(1)),
+    SpanKind LowCardinality(String) CODEC(ZSTD(1)),
+    DurationUInt64 UInt64 CODEC(ZSTD(1)),
+    StatusCode LowCardinality(String) CODEC(ZSTD(1)),
+    SpanAttributes Map(LowCardinality(String), String) CODEC(ZSTD(1)),
+    ResourceAttributes Map(LowCardinality(String), String) CODEC(ZSTD(1)),
+    EventsNested Nested (
+        Timestamp DateTime64(9),
+        Name LowCardinality(String),
+        Attributes Map(LowCardinality(String), String)
+    ) CODEC(ZSTD(1))
+) ENGINE = MergeTree()
+PARTITION BY toDate(Timestamp)
+ORDER BY (ServiceName, SpanName, toUnixTimestamp(Timestamp), TraceId);
+```
+
+### Tabla: `otel_logs`
+
+```sql
+CREATE TABLE otel_logs (
+    Timestamp DateTime64(9) CODEC(Delta, ZSTD(1)),
+    TraceId String CODEC(ZSTD(1)),
+    SpanId String CODEC(ZSTD(1)),
+    SeverityText LowCardinality(String) CODEC(ZSTD(1)),
+    SeverityNumber Int32 CODEC(ZSTD(1)),
+    ServiceName LowCardinality(String) CODEC(ZSTD(1)),
+    Body String CODEC(ZSTD(1)),
+    LogAttributes Map(LowCardinality(String), String) CODEC(ZSTD(1)),
+    ResourceAttributes Map(LowCardinality(String), String) CODEC(ZSTD(1))
+) ENGINE = MergeTree()
+PARTITION BY toDate(Timestamp)
+ORDER BY (ServiceName, SeverityText, toUnixTimestamp(Timestamp), TraceId);
 ```
 
 ---
 
-## Tipos esperados
+## 🔍 Ejemplo completo
 
 ```ts
-interface TraceNode {
-  traceId: string;
-  spanId: string;
-  parentSpanId?: string;
-  projectId: string;
-  function: string;
-  checkpoint: string;
-  description?: string;
-  inputData?: any;
-  outputData?: any;
-  error?: any;
-  type: 'input' | 'output';
-  status: boolean;
-  tags?: string[];
-  startTime: number;
-  endTime: number;
-  duration?: number;
-  source?: string;
+import { Trace, logger } from '@hemia/trace-manager';
+import { asyncContext } from '@hemia/app-context';
+
+class OrderController {
+  @Trace({ name: 'http-create-order', kind: 'SPAN_KIND_SERVER' })
+  async createOrder(req: Request) {
+    logger.info('Order request received', { userId: req.userId });
+    
+    const order = await this.orderService.create(req.body);
+    
+    logger.info('Order created successfully', { orderId: order.id });
+    return order;
+  }
+}
+
+class OrderService {
+  @Trace()
+  async create(orderData: any) {
+    // Span hijo automático (ParentSpanId = span del controller)
+    logger.debug('Validating order data');
+    
+    await this.validate(orderData);
+    const order = await this.repository.save(orderData);
+    
+    logger.info('Order persisted', { orderId: order.id });
+    return order;
+  }
+
+  @Trace({ name: 'validate-order-rules' })
+  private async validate(data: any) {
+    // Span nieto (hijo del método create)
+    if (!data.items?.length) {
+      logger.error('Validation failed: no items');
+      throw new Error('Order must have items');
+    }
+  }
 }
 ```
 
+**Resultado en ClickHouse:**
+
+3 spans jerárquicos:
+1. `http-create-order` (root, SPAN_KIND_SERVER)
+2. `OrderService.create` (child, SPAN_KIND_INTERNAL)
+3. `validate-order-rules` (grandchild, SPAN_KIND_INTERNAL)
+
+Y múltiples logs correlacionados con el mismo `TraceId`.
+
+---
+
+## 📝 Buenas Prácticas
+
+1. **Usar `@Trace()` en capas de negocio críticas**: Controllers, Services, Repositories
+2. **Logger en puntos de decisión**: Validaciones, llamadas externas, errores
+3. **Atributos significativos**: Agregar IDs de entidades, estados, providers
+4. **Nombres descriptivos**: Usar `name` en `@Trace()` para operaciones complejas
+5. **Sanitización automática**: Los inputs/outputs se sanitizan para evitar datos sensibles
+
 ---
 
-## Requisitos
+## 🛠️ Utilidades
 
-*  `@hemia/app-context` para contexto y persistencia
+### `sanitizeArgs()` y `toSafeJSON()`
+
+Utilidades internas que previenen:
+- Serialización de objetos circulares
+- Exposición de contraseñas/tokens en atributos
+- Overflow de tamaño en ClickHouse
+
+---
+
+## 📚 Dependencias
+
+- `@hemia/app-context` - Manejo de contexto con AsyncLocalStorage
+- `uuid` - Generación de IDs únicos para spans
 
 ---
 
-## Licencia
+## 📄 Licencia
 
 MIT
 
 ---
 
-## Autor
+## 👨‍💻 Autor
+
+**Hemia Technologies**
+
+---
+
+## 🔗 Recursos
 
-Hemia Technologies
+- [OpenTelemetry Specification](https://opentelemetry.io/docs/specs/otel/)
+- [ClickHouse Documentation](https://clickhouse.com/docs)
+- [AsyncLocalStorage Node.js](https://nodejs.org/api/async_context.html)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hemia/trace-manager",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Gestor de trazas para registrar logs, errores y evento",
   "main": "dist/hemia-trace-manager.js",
   "module": "dist/hemia-trace-manager.esm.js",
@@ -14,7 +14,6 @@
   },
   "devDependencies": {
     "@hemia/app-context": "^0.0.3",
-    "@hemia/db-manager": "^0.0.6",
     "@rollup/plugin-commonjs": "^26.0.1",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.2.3",