@hemia/trace-manager 0.0.2 → 0.0.4

package/README.md

@@ -1,116 +1,517 @@
 # @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:**
 
-### ✅ `TraceManager<T>`
+- 🔹 Crea span automáticamente con `SpanId` único
+- 🔹 Captura **metadata** de argumentos (tipos, cantidad) - no valores completos
+- 🔹 Captura **metadata** de resultados (tipo, isArray, length) - no valores completos
+- 🔹 Registra excepciones como eventos (`EventsNested`)
+- 🔹 Calcula duración en nanosegundos (`DurationUInt64`)
+- 🔹 Propaga contexto automáticamente a métodos hijos
+- 🔹 **Privacy-first**: No serializa valores sensibles, solo metadata
 
-Clase encargada de registrar y consultar trazas desde un repositorio MongoDB usando `NoSQLRepository`.
+#### **Uso básico:**
+
+```ts
+import { Trace } from '@hemia/trace-manager';
+
+class UserService {
+  @Trace()
+  async createUser(userData: any) {
+    // El decorador captura automáticamente:
+    // - Metadata de input: tipo, cantidad de args (NO valores completos)
+    // - Metadata de output: tipo, isArray, length (NO valores completos)
+    // - Duración de ejecución en nanosegundos
+    // - Excepciones si ocurren (con stacktrace)
+    
+    const user = await this.repository.save(userData);
+    return user;
+  }
+
+  @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
 
-class MiServicio {
-  @Traceable({ ck: 'MiServicio', fn: 'procesar' })
-  async procesar(data: any) {
-    // lógica
-    return { ok: true };
+#### **Uso:**
+
+```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
+```
 
 ---
 
-### ✅ `addTrace()` y `endTrace()`
+## 🏗️ Estructura de Datos
+
+### **TraceSpan** (Span de OpenTelemetry)
 
-Funciones internas para agregar nodos de traza al contexto.
+Mapea directamente con la tabla `otel_traces` de ClickHouse:
 
 ```ts
-const spanId = addTrace('Login', 'authUser', 'input', { email }, 'Inicio de login');
-// lógica
-endTrace(spanId, true, { userId });
+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
+}
 ```
 
 ---
 
-## Tipos esperados
+## 🔗 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.
+
+### **Requisitos:**
+
+El contexto debe ser inicializado previamente usando `@hemia/app-context` (generalmente en un middleware HTTP):
 
 ```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 { 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);
+```
+
+---
+
+## 🔍 Ejemplo completo
+
+```ts
+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`.
+
 ---
 
-## Requisitos
+## 📝 Buenas Prácticas
 
-*  `@hemia/app-context` para contexto y persistencia
+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. **Metadata approach**: El decorador captura metadata (tipos, cantidad) en lugar de valores completos
+6. **Privacy by default**: No se serializan valores sensibles como passwords o tokens
 
 ---
 
-## Licencia
+## 🛠️ Utilidades
+
+### Helpers para SpanAttributes (Metadata Approach)
+
+El paquete incluye utilidades para agregar metadata en lugar de serializar datos completos, siguiendo las mejores prácticas de observabilidad:
+
+#### **`addArgsMetadata(attributes, args)`**
+Agrega metadata de argumentos de función:
+```ts
+import { addArgsMetadata } from '@hemia/trace-manager';
+
+const args = ['user@test.com', 123, { name: 'John' }];
+addArgsMetadata(span.SpanAttributes, args);
+
+// Resultado:
+// {
+//   "app.method.args.count": "3",
+//   "app.method.args.types": "string,number,object"
+// }
+```
+
+#### **`addResultMetadata(attributes, result)`**
+Agrega metadata de resultado de función:
+```ts
+import { addResultMetadata } from '@hemia/trace-manager';
+
+const result = [{ id: 1 }, { id: 2 }];
+addResultMetadata(span.SpanAttributes, result);
+
+// Resultado:
+// {
+//   "app.method.result.type": "object",
+//   "app.method.result.isArray": "true",
+//   "app.method.result.length": "2"
+// }
+```
+
+#### **`addRequestBodyMetadata(attributes, body, prefix?)`**
+Agrega metadata de Request body (para middlewares HTTP):
+```ts
+import { addRequestBodyMetadata } from '@hemia/trace-manager';
+
+const reqBody = { email: 'user@test.com', password: '***' };
+addRequestBodyMetadata(span.SpanAttributes, reqBody);
+
+// Resultado:
+// {
+//   "http.request.body.exists": "true",
+//   "http.request.body.type": "object",
+//   "http.request.body.keys": "email,password",
+//   "http.request.body.keyCount": "2"
+// }
+```
+
+#### **`addResponseBodyMetadata(attributes, body, isError, prefix?)`**
+Agrega metadata de Response body con captura inteligente de errores:
+```ts
+import { addResponseBodyMetadata } from '@hemia/trace-manager';
+
+const errorBody = { 
+  code: 'AUTH_ERROR', 
+  message: 'Invalid credentials' 
+};
+
+addResponseBodyMetadata(
+  span.SpanAttributes, 
+  errorBody, 
+  true // isError = true activa captura de mensaje
+);
+
+// Resultado:
+// {
+//   "http.response.body.exists": "true",
+//   "http.response.body.type": "object",
+//   "http.response.body.keys": "code,message",
+//   "http.response.body.keyCount": "2",
+//   "http.response.error.code": "AUTH_ERROR",
+//   "http.response.error.message": "Invalid credentials"
+// }
+```
+
+#### **`addObjectMetadata(attributes, data, prefix)`**
+Agrega metadata genérica de cualquier objeto:
+```ts
+import { addObjectMetadata } from '@hemia/trace-manager';
+
+const payload = { items: [1, 2, 3], total: 100 };
+addObjectMetadata(span.SpanAttributes, payload, 'order.payload');
+
+// Resultado:
+// {
+//   "order.payload.exists": "true",
+//   "order.payload.type": "object",
+//   "order.payload.keys": "items,total",
+//   "order.payload.keyCount": "2"
+// }
+```
+
+### Uso en Middleware Custom
+
+```ts
+import { 
+  addRequestBodyMetadata, 
+  addResponseBodyMetadata 
+} from '@hemia/trace-manager';
+
+export const customMiddleware = () => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // ... inicializar span ...
+
+    res.on('finish', () => {
+      const isError = res.statusCode >= 400;
+
+      if (isError) {
+        // Capturar metadata en lugar de cuerpos completos
+        addRequestBodyMetadata(
+          span.SpanAttributes,
+          req.body
+        );
+
+        addResponseBodyMetadata(
+          span.SpanAttributes,
+          res.locals.responseBody,
+          isError // Captura mensaje de error si existe
+        );
+      }
+    });
+
+    next();
+  };
+};
+```
+
+### Ventajas del Metadata Approach
+
+✅ **Menor storage**: 10-20 bytes vs potencialmente KB de JSON  
+✅ **Privacy by default**: No serializa valores sensibles (passwords, tokens)  
+✅ **Mejor cardinality**: Más eficiente para queries en ClickHouse  
+✅ **Suficiente para debugging**: Keys y tipos son suficientes para diagnosticar  
+✅ **Consistencia**: Mismo approach en decoradores y middlewares  
+
+### `sanitizeArgs()` y `toSafeJSON()`
+
+Utilidades legacy que previenen:
+- Serialización de objetos circulares
+- Filtrado de Request/Response de Express
+- Overflow de tamaño en ClickHouse
+
+**⚠️ Nota**: El decorador `@Trace` ahora usa metadata en lugar de estas utilidades, pero siguen disponibles para compatibilidad.
+
+---
+
+## 📚 Dependencias
+
+- `@hemia/app-context` (^0.0.6) - Manejo de contexto con AsyncLocalStorage
+- `uuid` (^10.0.0) - Generación de IDs únicos para spans
+
+## 🔄 Versión Actual
+
+**v0.0.3** - Metadata approach implementado (Noviembre 2025)
+
+---
+
+## 📄 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/dist/hemia-trace-manager.esm.js

@@ -1 +1 @@
-import{asyncContext as t}from"@hemia/app-context";var e;!function(t){t.TRACE="x-trace-id",t.CORRELATION="x-correlation-id"}(e||(e={}));const n={DEBUG:5,INFO:9,WARN:13,ERROR:17,FATAL:21};const r=new class{constructor(t){this.defaultServiceName=t}log(e,r,o){const s=t.getStore();if(!s)return console.warn("[Logger] No active context. Log not traced."),void console.log(`[${e}] ${r}`,o);const a={Timestamp:(new Date).toISOString(),TraceId:s.traceId,SpanId:s.spanId,TraceFlags:1,SeverityText:e,SeverityNumber:n[e],ServiceName:s.serviceName,Body:r,LogAttributes:this.stringifyAttributes(o||{}),ResourceAttributes:s.traceContext.resourceAttributes};s.traceContext.logs.push(a),"production"!==process.env.NODE_ENV&&console.log(`[${e}] [TraceId:${s.traceId.substring(0,8)}...] ${r}`,o||"")}stringifyAttributes(t){const e={};for(const[n,r]of Object.entries(t))if(null==r)e[n]="";else if("string"==typeof r)e[n]=r;else try{e[n]=JSON.stringify(r)}catch{e[n]=String(r)}return e}debug(t,e){this.log("DEBUG",t,e)}info(t,e){this.log("INFO",t,e)}warn(t,e){this.log("WARN",t,e)}error(t,e){this.log("ERROR",t,e)}fatal(t,e){this.log("FATAL",t,e)}};function o(t){try{const e=JSON.stringify(t,function(){const t=new WeakSet;return(e,n)=>{if(null===n)return null;if("object"==typeof n){if(t.has(n))return"[Circular]";t.add(n)}return"function"==typeof n?n.toString():n}}());return JSON.parse(e)}catch(e){return String(t)}}const s=["content-type","host","x-no-cookies","x-api-key","Authorization","origin"];function a(t){return t.map(t=>{if(function(t){return null!=t&&"object"==typeof t&&"string"==typeof t.method&&"string"==typeof t.url&&"object"==typeof t.headers}(t)){const e=s.reduce((e,n)=>{const r=n.toLowerCase();return t.headers[r]&&(e[r]=t.headers[r]),e},{});return{method:t.method,url:t.url,params:t.params,query:t.query,body:t.body,headers:e}}return function(t){return null!=t&&"object"==typeof t&&"number"==typeof t.statusCode&&"function"==typeof t.setHeader&&"function"==typeof t.end}(t)?"[ExpressResponseObject]":"function"==typeof t?"[Function next]":t})}for(var i,c=[],u=0;u<256;++u)c.push((u+256).toString(16).slice(1));var p=new Uint8Array(16);function d(){if(!i&&!(i="undefined"!=typeof crypto&&crypto.getRandomValues&&crypto.getRandomValues.bind(crypto)))throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");return i(p)}var f={randomUUID:"undefined"!=typeof crypto&&crypto.randomUUID&&crypto.randomUUID.bind(crypto)};function g(t,e,n){if(f.randomUUID&&!t)return f.randomUUID();var r=(t=t||{}).random||(t.rng||d)();return r[6]=15&r[6]|64,r[8]=63&r[8]|128,function(t,e=0){return(c[t[e+0]]+c[t[e+1]]+c[t[e+2]]+c[t[e+3]]+"-"+c[t[e+4]]+c[t[e+5]]+"-"+c[t[e+6]]+c[t[e+7]]+"-"+c[t[e+8]]+c[t[e+9]]+"-"+c[t[e+10]]+c[t[e+11]]+c[t[e+12]]+c[t[e+13]]+c[t[e+14]]+c[t[e+15]]).toLowerCase()}(r)}function l(e){return function(n,r,s){const i=s?.value;if("function"!=typeof i)throw new Error("@Trace can only be applied to methods");s.value=async function(...s){const c=t.getStore();if(!c)return console.warn("[Trace] No active context. Skipping trace."),await i.apply(this,s);const u=g(),p=this?.constructor?.name||n.name||"UnknownClass",d=e?.name||`${p}.${r}`,f=process.hrtime.bigint(),l=(new Date).toISOString(),m=c.spanId,y={Timestamp:l,TraceId:c.traceId,SpanId:u,ParentSpanId:m,TraceState:"",ServiceName:c.serviceName,SpanName:d,SpanKind:e?.kind||"SPAN_KIND_INTERNAL",DurationUInt64:BigInt(0),StatusCode:"STATUS_CODE_UNSET",StatusMessage:"",SpanAttributes:{"code.function":r,"code.namespace":p,...e?.attributes},ResourceAttributes:c.traceContext.resourceAttributes,EventsNested:[],LinksNested:[]},S=c.spanId;c.spanId=u;try{const t=a(s);y.SpanAttributes["app.method.args"]=o(t),y.SpanAttributes["app.method.args.count"]=s.length.toString();const e=await i.apply(this,s),n=o(a(Array.isArray(e)?e:[e]));return y.SpanAttributes["app.method.result"]=n.substring(0,2e3),y.StatusCode="STATUS_CODE_OK",e}catch(t){const e={Timestamp:(new Date).toISOString(),Name:"exception",Attributes:{"exception.type":t.constructor?.name||"Error","exception.message":t.message||"Unknown error","exception.stacktrace":(t.stack||"").substring(0,5e3)}};throw y.EventsNested.push(e),y.StatusCode="STATUS_CODE_ERROR",y.StatusMessage=t.message||"Unhandled exception",t}finally{const t=process.hrtime.bigint();y.DurationUInt64=t-f,c.traceContext.spans.push(y),c.spanId=S}}}}export{l as Trace,e as TraceHeader,r as logger};
+import{asyncContext as t}from"@hemia/app-context";var e;!function(t){t.TRACE="x-trace-id",t.CORRELATION="x-correlation-id"}(e||(e={}));const r={DEBUG:5,INFO:9,WARN:13,ERROR:17,FATAL:21};const n=new class{constructor(t){this.defaultServiceName=t}log(e,n,o){const s=t.getStore();if(!s)return console.warn("[Logger] No active context. Log not traced."),void console.log(`[${e}] ${n}`,o);const i={Timestamp:(new Date).toISOString(),TraceId:s.traceId,SpanId:s.spanId,TraceFlags:1,SeverityText:e,SeverityNumber:r[e],ServiceName:s.serviceName,Body:n,LogAttributes:this.stringifyAttributes(o||{}),ResourceAttributes:s.traceContext.resourceAttributes};s.traceContext.logs.push(i),"production"!==process.env.NODE_ENV&&console.log(`[${e}] [TraceId:${s.traceId.substring(0,8)}...] ${n}`,o||"")}stringifyAttributes(t){const e={};for(const[r,n]of Object.entries(t))if(null==n)e[r]="";else if("string"==typeof n)e[r]=n;else try{e[r]=JSON.stringify(n)}catch{e[r]=String(n)}return e}debug(t,e){this.log("DEBUG",t,e)}info(t,e){this.log("INFO",t,e)}warn(t,e){this.log("WARN",t,e)}error(t,e){this.log("ERROR",t,e)}fatal(t,e){this.log("FATAL",t,e)}};for(var o,s=[],i=0;i<256;++i)s.push((i+256).toString(16).slice(1));var a=new Uint8Array(16);function c(){if(!o&&!(o="undefined"!=typeof crypto&&crypto.getRandomValues&&crypto.getRandomValues.bind(crypto)))throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");return o(a)}var p={randomUUID:"undefined"!=typeof crypto&&crypto.randomUUID&&crypto.randomUUID.bind(crypto)};function u(t,e,r){if(p.randomUUID&&!t)return p.randomUUID();var n=(t=t||{}).random||(t.rng||c)();return n[6]=15&n[6]|64,n[8]=63&n[8]|128,function(t,e=0){return(s[t[e+0]]+s[t[e+1]]+s[t[e+2]]+s[t[e+3]]+"-"+s[t[e+4]]+s[t[e+5]]+"-"+s[t[e+6]]+s[t[e+7]]+"-"+s[t[e+8]]+s[t[e+9]]+"-"+s[t[e+10]]+s[t[e+11]]+s[t[e+12]]+s[t[e+13]]+s[t[e+14]]+s[t[e+15]]).toLowerCase()}(n)}function g(t,e){t["app.method.args.count"]=e.length.toString(),t["app.method.args.types"]=e.map(t=>typeof t).join(",")}function y(t,e){t["app.method.result.type"]=typeof e,t["app.method.result.isArray"]=Array.isArray(e).toString(),t["app.method.result.length"]=Array.isArray(e)?e.length.toString():"1"}function d(t,e,r="http.request.body"){if(t[`${r}.exists`]=(!!e).toString(),t[`${r}.type`]=typeof e,e&&"object"==typeof e){const n=Object.keys(e);t[`${r}.keys`]=n.join(","),t[`${r}.keyCount`]=n.length.toString()}Array.isArray(e)&&(t[`${r}.isArray`]="true",t[`${r}.length`]=e.length.toString())}function l(t,e,r=!1,n="http.response.body"){if(t[`${n}.exists`]=(!!e).toString(),t[`${n}.type`]=typeof e,e&&"object"==typeof e){const r=Object.keys(e);t[`${n}.keys`]=r.join(","),t[`${n}.keyCount`]=r.length.toString()}Array.isArray(e)&&(t[`${n}.isArray`]="true",t[`${n}.length`]=e.length.toString()),r&&e&&(e.message&&(t["http.response.error.message"]=String(e.message).substring(0,500)),e.code&&(t["http.response.error.code"]=String(e.code)),e.error&&(t["http.response.error.type"]=String(e.error).substring(0,200)))}function f(t,e,r){if(e){if(t[`${r}.exists`]="true",t[`${r}.type`]=typeof e,"object"==typeof e&&!Array.isArray(e)){const n=Object.keys(e);t[`${r}.keys`]=n.join(","),t[`${r}.keyCount`]=n.length.toString()}Array.isArray(e)&&(t[`${r}.isArray`]="true",t[`${r}.length`]=e.length.toString(),e.length>0&&(t[`${r}.firstItemType`]=typeof e[0])),"string"==typeof e?t[`${r}.value`]=e.substring(0,200):"number"!=typeof e&&"boolean"!=typeof e||(t[`${r}.value`]=String(e))}else t[`${r}.exists`]="false"}function S(e){return function(r,n,o){const s=o?.value;if("function"!=typeof s)throw new Error("@Trace can only be applied to methods");o.value=async function(...o){const i=t.getStore();if(!i)return console.warn("[Trace] No active context. Skipping trace."),await s.apply(this,o);const a=u(),c=this?.constructor?.name||r.name||"UnknownClass",p=e?.name||`${c}.${n}`,d=process.hrtime.bigint(),l=(new Date).toISOString(),f=i.spanId,S={Timestamp:l,TraceId:i.traceId,SpanId:a,ParentSpanId:f,TraceState:"",ServiceName:i.serviceName,SpanName:p,SpanKind:e?.kind||"SPAN_KIND_INTERNAL",DurationUInt64:BigInt(0),StatusCode:"STATUS_CODE_UNSET",StatusMessage:"",SpanAttributes:{"code.function":n,"code.namespace":c,...e?.attributes},ResourceAttributes:i.traceContext.resourceAttributes,EventsNested:[],LinksNested:[]},m=i.spanId;i.spanId=a;try{g(S.SpanAttributes,o);const t=await s.apply(this,o);return y(S.SpanAttributes,t),S.StatusCode="STATUS_CODE_OK",t}catch(t){const e={Timestamp:(new Date).toISOString(),Name:"exception",Attributes:{"exception.type":t.constructor?.name||"Error","exception.message":t.message||"Unknown error","exception.stacktrace":String(t.stack||"").substring(0,5e3)}};throw S.EventsNested.push(e),S.StatusCode="STATUS_CODE_ERROR",S.StatusMessage=t.message||"Unhandled exception",t}finally{const t=process.hrtime.bigint();S.DurationUInt64=t-d,i.traceContext.spans.push(S),i.spanId=m}}}}export{S as Trace,e as TraceHeader,g as addArgsMetadata,f as addObjectMetadata,d as addRequestBodyMetadata,l as addResponseBodyMetadata,y as addResultMetadata,n as logger};

package/dist/hemia-trace-manager.js

@@ -1 +1 @@
-"use strict";var t,e=require("@hemia/app-context");exports.TraceHeader=void 0,(t=exports.TraceHeader||(exports.TraceHeader={})).TRACE="x-trace-id",t.CORRELATION="x-correlation-id";const r={DEBUG:5,INFO:9,WARN:13,ERROR:17,FATAL:21};const n=new class{constructor(t){this.defaultServiceName=t}log(t,n,o){const s=e.asyncContext.getStore();if(!s)return console.warn("[Logger] No active context. Log not traced."),void console.log(`[${t}] ${n}`,o);const a={Timestamp:(new Date).toISOString(),TraceId:s.traceId,SpanId:s.spanId,TraceFlags:1,SeverityText:t,SeverityNumber:r[t],ServiceName:s.serviceName,Body:n,LogAttributes:this.stringifyAttributes(o||{}),ResourceAttributes:s.traceContext.resourceAttributes};s.traceContext.logs.push(a),"production"!==process.env.NODE_ENV&&console.log(`[${t}] [TraceId:${s.traceId.substring(0,8)}...] ${n}`,o||"")}stringifyAttributes(t){const e={};for(const[r,n]of Object.entries(t))if(null==n)e[r]="";else if("string"==typeof n)e[r]=n;else try{e[r]=JSON.stringify(n)}catch{e[r]=String(n)}return e}debug(t,e){this.log("DEBUG",t,e)}info(t,e){this.log("INFO",t,e)}warn(t,e){this.log("WARN",t,e)}error(t,e){this.log("ERROR",t,e)}fatal(t,e){this.log("FATAL",t,e)}};function o(t){try{const e=JSON.stringify(t,function(){const t=new WeakSet;return(e,r)=>{if(null===r)return null;if("object"==typeof r){if(t.has(r))return"[Circular]";t.add(r)}return"function"==typeof r?r.toString():r}}());return JSON.parse(e)}catch(e){return String(t)}}const s=["content-type","host","x-no-cookies","x-api-key","Authorization","origin"];function a(t){return t.map(t=>{if(function(t){return null!=t&&"object"==typeof t&&"string"==typeof t.method&&"string"==typeof t.url&&"object"==typeof t.headers}(t)){const e=s.reduce((e,r)=>{const n=r.toLowerCase();return t.headers[n]&&(e[n]=t.headers[n]),e},{});return{method:t.method,url:t.url,params:t.params,query:t.query,body:t.body,headers:e}}return function(t){return null!=t&&"object"==typeof t&&"number"==typeof t.statusCode&&"function"==typeof t.setHeader&&"function"==typeof t.end}(t)?"[ExpressResponseObject]":"function"==typeof t?"[Function next]":t})}for(var i,c=[],u=0;u<256;++u)c.push((u+256).toString(16).slice(1));var p=new Uint8Array(16);function d(){if(!i&&!(i="undefined"!=typeof crypto&&crypto.getRandomValues&&crypto.getRandomValues.bind(crypto)))throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");return i(p)}var f={randomUUID:"undefined"!=typeof crypto&&crypto.randomUUID&&crypto.randomUUID.bind(crypto)};function g(t,e,r){if(f.randomUUID&&!t)return f.randomUUID();var n=(t=t||{}).random||(t.rng||d)();return n[6]=15&n[6]|64,n[8]=63&n[8]|128,function(t,e=0){return(c[t[e+0]]+c[t[e+1]]+c[t[e+2]]+c[t[e+3]]+"-"+c[t[e+4]]+c[t[e+5]]+"-"+c[t[e+6]]+c[t[e+7]]+"-"+c[t[e+8]]+c[t[e+9]]+"-"+c[t[e+10]]+c[t[e+11]]+c[t[e+12]]+c[t[e+13]]+c[t[e+14]]+c[t[e+15]]).toLowerCase()}(n)}exports.Trace=function(t){return function(r,n,s){const i=s?.value;if("function"!=typeof i)throw new Error("@Trace can only be applied to methods");s.value=async function(...s){const c=e.asyncContext.getStore();if(!c)return console.warn("[Trace] No active context. Skipping trace."),await i.apply(this,s);const u=g(),p=this?.constructor?.name||r.name||"UnknownClass",d=t?.name||`${p}.${n}`,f=process.hrtime.bigint(),l=(new Date).toISOString(),y=c.spanId,m={Timestamp:l,TraceId:c.traceId,SpanId:u,ParentSpanId:y,TraceState:"",ServiceName:c.serviceName,SpanName:d,SpanKind:t?.kind||"SPAN_KIND_INTERNAL",DurationUInt64:BigInt(0),StatusCode:"STATUS_CODE_UNSET",StatusMessage:"",SpanAttributes:{"code.function":n,"code.namespace":p,...t?.attributes},ResourceAttributes:c.traceContext.resourceAttributes,EventsNested:[],LinksNested:[]},S=c.spanId;c.spanId=u;try{const t=a(s);m.SpanAttributes["app.method.args"]=o(t),m.SpanAttributes["app.method.args.count"]=s.length.toString();const e=await i.apply(this,s),r=o(a(Array.isArray(e)?e:[e]));return m.SpanAttributes["app.method.result"]=r.substring(0,2e3),m.StatusCode="STATUS_CODE_OK",e}catch(t){const e={Timestamp:(new Date).toISOString(),Name:"exception",Attributes:{"exception.type":t.constructor?.name||"Error","exception.message":t.message||"Unknown error","exception.stacktrace":(t.stack||"").substring(0,5e3)}};throw m.EventsNested.push(e),m.StatusCode="STATUS_CODE_ERROR",m.StatusMessage=t.message||"Unhandled exception",t}finally{const t=process.hrtime.bigint();m.DurationUInt64=t-f,c.traceContext.spans.push(m),c.spanId=S}}}},exports.logger=n;
+"use strict";var t,e=require("@hemia/app-context");exports.TraceHeader=void 0,(t=exports.TraceHeader||(exports.TraceHeader={})).TRACE="x-trace-id",t.CORRELATION="x-correlation-id";const r={DEBUG:5,INFO:9,WARN:13,ERROR:17,FATAL:21};const n=new class{constructor(t){this.defaultServiceName=t}log(t,n,o){const s=e.asyncContext.getStore();if(!s)return console.warn("[Logger] No active context. Log not traced."),void console.log(`[${t}] ${n}`,o);const a={Timestamp:(new Date).toISOString(),TraceId:s.traceId,SpanId:s.spanId,TraceFlags:1,SeverityText:t,SeverityNumber:r[t],ServiceName:s.serviceName,Body:n,LogAttributes:this.stringifyAttributes(o||{}),ResourceAttributes:s.traceContext.resourceAttributes};s.traceContext.logs.push(a),"production"!==process.env.NODE_ENV&&console.log(`[${t}] [TraceId:${s.traceId.substring(0,8)}...] ${n}`,o||"")}stringifyAttributes(t){const e={};for(const[r,n]of Object.entries(t))if(null==n)e[r]="";else if("string"==typeof n)e[r]=n;else try{e[r]=JSON.stringify(n)}catch{e[r]=String(n)}return e}debug(t,e){this.log("DEBUG",t,e)}info(t,e){this.log("INFO",t,e)}warn(t,e){this.log("WARN",t,e)}error(t,e){this.log("ERROR",t,e)}fatal(t,e){this.log("FATAL",t,e)}};for(var o,s=[],a=0;a<256;++a)s.push((a+256).toString(16).slice(1));var i=new Uint8Array(16);function c(){if(!o&&!(o="undefined"!=typeof crypto&&crypto.getRandomValues&&crypto.getRandomValues.bind(crypto)))throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");return o(i)}var p={randomUUID:"undefined"!=typeof crypto&&crypto.randomUUID&&crypto.randomUUID.bind(crypto)};function u(t,e,r){if(p.randomUUID&&!t)return p.randomUUID();var n=(t=t||{}).random||(t.rng||c)();return n[6]=15&n[6]|64,n[8]=63&n[8]|128,function(t,e=0){return(s[t[e+0]]+s[t[e+1]]+s[t[e+2]]+s[t[e+3]]+"-"+s[t[e+4]]+s[t[e+5]]+"-"+s[t[e+6]]+s[t[e+7]]+"-"+s[t[e+8]]+s[t[e+9]]+"-"+s[t[e+10]]+s[t[e+11]]+s[t[e+12]]+s[t[e+13]]+s[t[e+14]]+s[t[e+15]]).toLowerCase()}(n)}function d(t,e){t["app.method.args.count"]=e.length.toString(),t["app.method.args.types"]=e.map(t=>typeof t).join(",")}function g(t,e){t["app.method.result.type"]=typeof e,t["app.method.result.isArray"]=Array.isArray(e).toString(),t["app.method.result.length"]=Array.isArray(e)?e.length.toString():"1"}exports.Trace=function(t){return function(r,n,o){const s=o?.value;if("function"!=typeof s)throw new Error("@Trace can only be applied to methods");o.value=async function(...o){const a=e.asyncContext.getStore();if(!a)return console.warn("[Trace] No active context. Skipping trace."),await s.apply(this,o);const i=u(),c=this?.constructor?.name||r.name||"UnknownClass",p=t?.name||`${c}.${n}`,y=process.hrtime.bigint(),l=(new Date).toISOString(),S=a.spanId,f={Timestamp:l,TraceId:a.traceId,SpanId:i,ParentSpanId:S,TraceState:"",ServiceName:a.serviceName,SpanName:p,SpanKind:t?.kind||"SPAN_KIND_INTERNAL",DurationUInt64:BigInt(0),StatusCode:"STATUS_CODE_UNSET",StatusMessage:"",SpanAttributes:{"code.function":n,"code.namespace":c,...t?.attributes},ResourceAttributes:a.traceContext.resourceAttributes,EventsNested:[],LinksNested:[]},h=a.spanId;a.spanId=i;try{d(f.SpanAttributes,o);const t=await s.apply(this,o);return g(f.SpanAttributes,t),f.StatusCode="STATUS_CODE_OK",t}catch(t){const e={Timestamp:(new Date).toISOString(),Name:"exception",Attributes:{"exception.type":t.constructor?.name||"Error","exception.message":t.message||"Unknown error","exception.stacktrace":String(t.stack||"").substring(0,5e3)}};throw f.EventsNested.push(e),f.StatusCode="STATUS_CODE_ERROR",f.StatusMessage=t.message||"Unhandled exception",t}finally{const t=process.hrtime.bigint();f.DurationUInt64=t-y,a.traceContext.spans.push(f),a.spanId=h}}}},exports.addArgsMetadata=d,exports.addObjectMetadata=function(t,e,r){if(e){if(t[`${r}.exists`]="true",t[`${r}.type`]=typeof e,"object"==typeof e&&!Array.isArray(e)){const n=Object.keys(e);t[`${r}.keys`]=n.join(","),t[`${r}.keyCount`]=n.length.toString()}Array.isArray(e)&&(t[`${r}.isArray`]="true",t[`${r}.length`]=e.length.toString(),e.length>0&&(t[`${r}.firstItemType`]=typeof e[0])),"string"==typeof e?t[`${r}.value`]=e.substring(0,200):"number"!=typeof e&&"boolean"!=typeof e||(t[`${r}.value`]=String(e))}else t[`${r}.exists`]="false"},exports.addRequestBodyMetadata=function(t,e,r="http.request.body"){if(t[`${r}.exists`]=(!!e).toString(),t[`${r}.type`]=typeof e,e&&"object"==typeof e){const n=Object.keys(e);t[`${r}.keys`]=n.join(","),t[`${r}.keyCount`]=n.length.toString()}Array.isArray(e)&&(t[`${r}.isArray`]="true",t[`${r}.length`]=e.length.toString())},exports.addResponseBodyMetadata=function(t,e,r=!1,n="http.response.body"){if(t[`${n}.exists`]=(!!e).toString(),t[`${n}.type`]=typeof e,e&&"object"==typeof e){const r=Object.keys(e);t[`${n}.keys`]=r.join(","),t[`${n}.keyCount`]=r.length.toString()}Array.isArray(e)&&(t[`${n}.isArray`]="true",t[`${n}.length`]=e.length.toString()),r&&e&&(e.message&&(t["http.response.error.message"]=String(e.message).substring(0,500)),e.code&&(t["http.response.error.code"]=String(e.code)),e.error&&(t["http.response.error.type"]=String(e.error).substring(0,200)))},exports.addResultMetadata=g,exports.logger=n;

package/dist/types/index.d.ts

@@ -3,3 +3,4 @@ export { TraceContext } from "./types/traceContext";
 export { TraceOptions } from "./types/traceOptions";
 export { logger } from "./log/Logger";
 export { Trace } from "./decorator/Traceable";
+export { addArgsMetadata, addResultMetadata, addRequestBodyMetadata, addResponseBodyMetadata, addObjectMetadata } from "./utils/SpanAttributesHelper";

package/dist/types/utils/SpanAttributesHelper.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Utilidades para agregar metadata de objetos a SpanAttributes
+ * siguiendo el principio de metadata sobre serialización completa
+ */
+/**
+ * Agrega metadata de argumentos de entrada a los SpanAttributes
+ * @param attributes - Objeto de atributos donde agregar metadata
+ * @param args - Array de argumentos a analizar
+ */
+export declare function addArgsMetadata(attributes: Record<string, string>, args: any[]): void;
+/**
+ * Agrega metadata de resultado/output a los SpanAttributes
+ * @param attributes - Objeto de atributos donde agregar metadata
+ * @param result - Resultado a analizar
+ */
+export declare function addResultMetadata(attributes: Record<string, string>, result: any): void;
+/**
+ * Agrega metadata de Request body a SpanAttributes (para middlewares HTTP)
+ * @param attributes - Objeto de atributos donde agregar metadata
+ * @param body - Body del request
+ * @param prefix - Prefijo para las keys (default: 'http.request.body')
+ */
+export declare function addRequestBodyMetadata(attributes: Record<string, string>, body: any, prefix?: string): void;
+/**
+ * Agrega metadata de Response body a SpanAttributes (para middlewares HTTP)
+ * Solo agrega información extendida en caso de errores
+ * @param attributes - Objeto de atributos donde agregar metadata
+ * @param body - Body del response
+ * @param isError - Si es una respuesta de error (statusCode >= 400)
+ * @param prefix - Prefijo para las keys (default: 'http.response.body')
+ */
+export declare function addResponseBodyMetadata(attributes: Record<string, string>, body: any, isError?: boolean, prefix?: string): void;
+/**
+ * Agrega metadata genérica de un objeto a SpanAttributes
+ * Útil para analizar cualquier tipo de payload
+ * @param attributes - Objeto de atributos donde agregar metadata
+ * @param data - Objeto a analizar
+ * @param prefix - Prefijo para las keys
+ */
+export declare function addObjectMetadata(attributes: Record<string, string>, data: any, prefix: string): void;

package/package.json

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