@hemia/trace-manager 0.0.1 → 0.0.3

package/README.md

@@ -1,117 +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/db-manager` y `@hemia/app-context` para contexto y persistencia
-* MongoDB como backend de traza
+### `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/dist/hemia-trace-manager.esm.js

@@ -1 +1 @@
-import{asyncContext as t}from"@hemia/app-context";import{Schema as e}from"@hemia/db-manager";var r;function n(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)}}!function(t){t.TRACE="x-trace-id",t.CORRELATION="x-correlation-id"}(r||(r={}));const o=["content-type","host","x-no-cookies","x-api-key","Authorization","origin"];function i(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=o.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 a,p=[],c=0;c<256;++c)p.push((c+256).toString(16).slice(1));var s=new Uint8Array(16);function u(){if(!a&&!(a="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 a(s)}var y={randomUUID:"undefined"!=typeof crypto&&crypto.randomUUID&&crypto.randomUUID.bind(crypto)};function d(t,e,r){if(y.randomUUID&&!t)return y.randomUUID();var n=(t=t||{}).random||(t.rng||u)();return n[6]=15&n[6]|64,n[8]=63&n[8]|128,function(t,e=0){return(p[t[e+0]]+p[t[e+1]]+p[t[e+2]]+p[t[e+3]]+"-"+p[t[e+4]]+p[t[e+5]]+"-"+p[t[e+6]]+p[t[e+7]]+"-"+p[t[e+8]]+p[t[e+9]]+"-"+p[t[e+10]]+p[t[e+11]]+p[t[e+12]]+p[t[e+13]]+p[t[e+14]]+p[t[e+15]]).toLowerCase()}(n)}function f(t){return function(e,r,o){const a="function"==typeof e;if(o){const p=o.value;if("function"!=typeof p)throw new Error("@Traceable can only be applied to methods, but was applied to "+typeof p);o.value=async function(...o){const c=a?e.name:this?.constructor?.name||e.constructor.name||"DEFAULT_CHECKPOINT",s=r;let u="";try{const e=n(i(o));u=g(t?.ck||c,t?.fn||s,"input",e,t?.description,t?.tags,t?.source)}catch(t){console.error("Error in Traceable decorator (addTrace):",t)}try{const t=await p.apply(this,o),e=Array.isArray(t)?t:[t],r=n(i(e));return m(u,!0,n(r)),t}catch(t){throw m(u,!1,n({error:t}),!0),t}}}else{const o=e[r];if("function"!=typeof o)throw new Error(`@Traceable can only be applied to methods, but was applied to ${typeof o}, without descriptor`);e[r]=async function(...p){const c=a?e.name:this?.constructor?.name||e.constructor.name||"DEFAULT_CHECKPOINT",s=r;let u="";try{const e=n(i(p));u=g(t?.ck||c,t?.fn||s,"input",e,t?.description,t?.tags,t?.source)}catch(t){console.error("Error in Traceable decorator (addTrace):",t)}try{const t=await o.apply(this,p),e=Array.isArray(t)?t:[t],r=n(i(e));return m(u,!0,n(r)),t}catch(t){throw m(u,!1,n({error:t}),!0),t}}}}}function g(e,r,n,o,i,a,p){const c=t.getStore();if(!c)return"";const s=c.projectId||"unknown",u=c.traceId,y=d(),f={description:i||"new trace input",tags:a,endTime:0,traceId:u,projectId:s,spanId:y,parentSpanId:c.parentSpanId,checkpoint:e,function:r,status:!0,type:n,startTime:Date.now(),inputData:o,source:p||"api"};return c.parentSpanId=y,c.trace.trace.push(f),y}function m(e,r,n,o){const i=t.getStore();if(!i)return;const a=i.trace.trace.find(t=>t.spanId===e);a&&(a.status=r,a.type="output",a.duration=Date.now()-a.startTime,a.endTime=Date.now(),a.outputData=n,o&&(a.error=n))}class l{constructor(t){this.repository=t}async save(t,e={}){if(!this.repository)throw new Error("Manager no inicializado. Llama a TraceManager primero.");const r={timestamp:(new Date).toISOString(),traceId:t,...e};return await this.repository.create(r)}async find(t,e){return await this.repository.find(t,e)}async findOne(t){return await this.repository.findOne(t)}async getById(t){return await this.repository.findById(t)}async update(t,e,r){return await this.repository.update(t,e,r)}async delete(t,e){await this.repository.delete(t,e)}async aggregate(t,e){return await this.repository.aggregate(t,e)}}const S=new e({traceId:{type:String,required:!0},projectId:{type:String,required:!0},meta:{userAgent:{type:String},environment:{type:String},platform:{type:String},ip:{type:String},event:{type:String},url:{type:String},path:{type:String},route:{type:String},tags:[{type:String}],user:{id:{type:String},email:{type:String}},browser:{name:{type:String},version:{type:String}},os:{name:{type:String},version:{type:String}},device:{model:{type:String},type:{type:String},vendor:{type:String}}},trace:{type:[new e({description:{type:String},traceId:{type:String,required:!0},spanId:{type:String,required:!0},parentSpanId:{type:String},projectId:{type:String,required:!0},parentId:{type:Number},checkpoint:{type:String,required:!0},function:{type:String,required:!0},status:{type:Boolean,required:!0},type:{type:String,enum:["input","output"],required:!0},startTime:{type:Number,default:()=>Date.now()},endTime:{type:Number,default:()=>Date.now()},duration:{type:Number},inputData:{type:e.Types.Mixed},outputData:{type:e.Types.Mixed},additionalData:{type:e.Types.Mixed},tags:[{type:String}],source:{type:String},error:{message:{type:String},code:{type:String},stack:{type:String}}},{_id:!1})],required:!0}});export{r as TraceHeader,l as TraceManager,S as TraceSchema,f as Traceable};
+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};

package/dist/hemia-trace-manager.js

@@ -1 +1 @@
-"use strict";var t,e=require("@hemia/app-context"),r=require("@hemia/db-manager");function n(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)}}exports.TraceHeader=void 0,(t=exports.TraceHeader||(exports.TraceHeader={})).TRACE="x-trace-id",t.CORRELATION="x-correlation-id";const o=["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=o.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,p=[],c=0;c<256;++c)p.push((c+256).toString(16).slice(1));var s=new Uint8Array(16);function u(){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(s)}var y={randomUUID:"undefined"!=typeof crypto&&crypto.randomUUID&&crypto.randomUUID.bind(crypto)};function d(t,e,r){if(y.randomUUID&&!t)return y.randomUUID();var n=(t=t||{}).random||(t.rng||u)();return n[6]=15&n[6]|64,n[8]=63&n[8]|128,function(t,e=0){return(p[t[e+0]]+p[t[e+1]]+p[t[e+2]]+p[t[e+3]]+"-"+p[t[e+4]]+p[t[e+5]]+"-"+p[t[e+6]]+p[t[e+7]]+"-"+p[t[e+8]]+p[t[e+9]]+"-"+p[t[e+10]]+p[t[e+11]]+p[t[e+12]]+p[t[e+13]]+p[t[e+14]]+p[t[e+15]]).toLowerCase()}(n)}function f(t,r,n,o,a,i,p){const c=e.asyncContext.getStore();if(!c)return"";const s=c.projectId||"unknown",u=c.traceId,y=d(),f={description:a||"new trace input",tags:i,endTime:0,traceId:u,projectId:s,spanId:y,parentSpanId:c.parentSpanId,checkpoint:t,function:r,status:!0,type:n,startTime:Date.now(),inputData:o,source:p||"api"};return c.parentSpanId=y,c.trace.trace.push(f),y}function g(t,r,n,o){const a=e.asyncContext.getStore();if(!a)return;const i=a.trace.trace.find(e=>e.spanId===t);i&&(i.status=r,i.type="output",i.duration=Date.now()-i.startTime,i.endTime=Date.now(),i.outputData=n,o&&(i.error=n))}const m=new r.Schema({traceId:{type:String,required:!0},projectId:{type:String,required:!0},meta:{userAgent:{type:String},environment:{type:String},platform:{type:String},ip:{type:String},event:{type:String},url:{type:String},path:{type:String},route:{type:String},tags:[{type:String}],user:{id:{type:String},email:{type:String}},browser:{name:{type:String},version:{type:String}},os:{name:{type:String},version:{type:String}},device:{model:{type:String},type:{type:String},vendor:{type:String}}},trace:{type:[new r.Schema({description:{type:String},traceId:{type:String,required:!0},spanId:{type:String,required:!0},parentSpanId:{type:String},projectId:{type:String,required:!0},parentId:{type:Number},checkpoint:{type:String,required:!0},function:{type:String,required:!0},status:{type:Boolean,required:!0},type:{type:String,enum:["input","output"],required:!0},startTime:{type:Number,default:()=>Date.now()},endTime:{type:Number,default:()=>Date.now()},duration:{type:Number},inputData:{type:r.Schema.Types.Mixed},outputData:{type:r.Schema.Types.Mixed},additionalData:{type:r.Schema.Types.Mixed},tags:[{type:String}],source:{type:String},error:{message:{type:String},code:{type:String},stack:{type:String}}},{_id:!1})],required:!0}});exports.TraceManager=class{constructor(t){this.repository=t}async save(t,e={}){if(!this.repository)throw new Error("Manager no inicializado. Llama a TraceManager primero.");const r={timestamp:(new Date).toISOString(),traceId:t,...e};return await this.repository.create(r)}async find(t,e){return await this.repository.find(t,e)}async findOne(t){return await this.repository.findOne(t)}async getById(t){return await this.repository.findById(t)}async update(t,e,r){return await this.repository.update(t,e,r)}async delete(t,e){await this.repository.delete(t,e)}async aggregate(t,e){return await this.repository.aggregate(t,e)}},exports.TraceSchema=m,exports.Traceable=function(t){return function(e,r,o){const i="function"==typeof e;if(o){const p=o.value;if("function"!=typeof p)throw new Error("@Traceable can only be applied to methods, but was applied to "+typeof p);o.value=async function(...o){const c=i?e.name:this?.constructor?.name||e.constructor.name||"DEFAULT_CHECKPOINT",s=r;let u="";try{const e=n(a(o));u=f(t?.ck||c,t?.fn||s,"input",e,t?.description,t?.tags,t?.source)}catch(t){console.error("Error in Traceable decorator (addTrace):",t)}try{const t=await p.apply(this,o),e=Array.isArray(t)?t:[t],r=n(a(e));return g(u,!0,n(r)),t}catch(t){throw g(u,!1,n({error:t}),!0),t}}}else{const o=e[r];if("function"!=typeof o)throw new Error(`@Traceable can only be applied to methods, but was applied to ${typeof o}, without descriptor`);e[r]=async function(...p){const c=i?e.name:this?.constructor?.name||e.constructor.name||"DEFAULT_CHECKPOINT",s=r;let u="";try{const e=n(a(p));u=f(t?.ck||c,t?.fn||s,"input",e,t?.description,t?.tags,t?.source)}catch(t){console.error("Error in Traceable decorator (addTrace):",t)}try{const t=await o.apply(this,p),e=Array.isArray(t)?t:[t],r=n(a(e));return g(u,!0,n(r)),t}catch(t){throw g(u,!1,n({error:t}),!0),t}}}}};
+"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;

package/dist/types/decorator/Traceable.d.ts

@@ -1,4 +1,6 @@
-import { ITraceOptions } from "../types/traceOptions";
-export declare function Traceable(options?: ITraceOptions): <T extends (...args: any[]) => any>(target: any, key: string, descriptor?: PropertyDescriptor) => void;
-export declare function addTrace(checkPoint: string, functionCode: string, type: "input" | "output", data?: any, description?: string, tags?: string[], source?: string): string;
-export declare function endTrace(spanId: string, status: boolean, data?: any, isError?: boolean): void;
+import { TraceOptions } from "../types/traceOptions";
+/**
+ * Decorador que captura método como Span en formato OpenTelemetry/ClickHouse
+ * Usa AsyncLocalStorage para propagar contexto automáticamente
+ */
+export declare function Trace(options?: TraceOptions): <T extends (...args: any[]) => any>(target: any, key: string, descriptor: PropertyDescriptor) => void;

package/dist/types/index.d.ts

@@ -1,7 +1,5 @@
 export { TraceHeader } from "./types/traceHeadersNames";
 export { TraceContext } from "./types/traceContext";
-export { ITraceOptions } from "./types/traceOptions";
-export { Traceable } from "./decorator/Traceable";
-export { TraceManager } from "./TraceManager";
-export { Trace, ITrace } from "./types/traceModel";
-export { TraceSchema } from "./types/traceSchema";
+export { TraceOptions } from "./types/traceOptions";
+export { logger } from "./log/Logger";
+export { Trace } from "./decorator/Traceable";

package/dist/types/log/Logger.d.ts

@@ -0,0 +1,15 @@
+export declare class Logger {
+    private defaultServiceName?;
+    constructor(defaultServiceName?: string | undefined);
+    /**
+     * Logs que se correlacionan automáticamente con el TraceId activo
+     */
+    private log;
+    private stringifyAttributes;
+    debug(message: string, attributes?: Record<string, any>): void;
+    info(message: string, attributes?: Record<string, any>): void;
+    warn(message: string, attributes?: Record<string, any>): void;
+    error(message: string, attributes?: Record<string, any>): void;
+    fatal(message: string, attributes?: Record<string, any>): void;
+}
+export declare const logger: Logger;

package/dist/types/types/traceOptions.d.ts

@@ -1,19 +1,6 @@
-/**
- * Opciones para el trazado de la ejecución de una función o proceso.
- *
- * @property {string} ck - Clave o identificador único para el trazo.
- * @property {string} fn - Nombre de la función o proceso que se está trazando.
- * @property {string} st - Estado inicial o mensaje que indica el inicio del trazo.
- * @property {string} [errSt] - Estado o mensaje que describe el error (opcional).
- * @property {string} [errCode] - Código que identifica el tipo de error (opcional).
- */
-export interface ITraceOptions {
-    ck?: string;
-    fn?: string;
-    st?: string;
-    errSt?: string;
-    errCode?: string;
-    description?: string;
-    tags?: string[];
-    source?: 'api' | 'web' | 'mobile' | 'cron' | 'system' | string;
+import { TraceSpan } from "@hemia/app-context";
+export interface TraceOptions {
+    name?: string;
+    kind?: TraceSpan['SpanKind'];
+    attributes?: Record<string, string>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hemia/trace-manager",
-  "version": "0.0.1",
+  "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",
@@ -13,8 +13,7 @@
     "test": "jest --passWithNoTests --detectOpenHandles"
   },
   "devDependencies": {
-    "@hemia/app-context": "^0.0.1",
-    "@hemia/db-manager": "^0.0.1",
+    "@hemia/app-context": "^0.0.3",
     "@rollup/plugin-commonjs": "^26.0.1",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.2.3",

package/dist/types/TraceManager.d.ts

@@ -1,50 +0,0 @@
-import { AggregateOptions, ClientSession, NoSQLOptions, NoSQLRepository, PipelineStage, FilterQuery, Document } from "@hemia/db-manager";
-export declare class TraceManager<T extends Document> {
-    private repository;
-    constructor(service: NoSQLRepository<T>);
-    /**
- * Servicio que permite guardar LOGS
- * @param level - Nivel del Log
- * @param message - Mensaje
- * @param traceId - Trace ID
- * @param trace - Traza
- * @param additionalData - Datos adicionales
- * @returns Documento guardado
- */
-    save(traceId: string, additionalData?: Partial<T>): Promise<T | null>;
-    /**
-     * Servicio que permite buscar documentos en la colección
-     * @param filter Filtros que se aplican en la colección
-     * @returns Lista de documentos de la colección
-     */
-    find(filter: FilterQuery<T>, options?: NoSQLOptions): Promise<T[]>;
-    /**
- * Servicio que permite buscar un documento en la colleción
- * @param filter - Filtros de la colección
- * @returns Documentos de la colección
- */
-    findOne(filter: FilterQuery<T>): Promise<T | null>;
-    /**
-     * Servicio que permite obtener un documento por ID
-     * @param id - Identificador del documento
-     * @returns Documento
-     */
-    getById(id: string): Promise<T | null>;
-    /**
-     * Serivicio para actualizar documentos en la base de datos
-     * @param filter - criterio de actualización
-     * @param updateData - Datos del documento a actualizar
-     * @returns Documento actualizado
-     */
-    update(filter: FilterQuery<T>, updateData: Partial<T>, session?: ClientSession): Promise<T | null>;
-    /**
-     * Servicio para eliminar un documento de la base de datos
-     * @param id - Identificador del documento
-     * @returns Documento Eliminado
-     */
-    delete(filter: FilterQuery<T>, session?: ClientSession): Promise<void>;
-    /**
-    * Ejecuta una consulta de agregación con un pipeline personalizado.
-    */
-    aggregate(pipeline: PipelineStage[], options?: AggregateOptions): Promise<any[]>;
-}

package/dist/types/types/traceModel.d.ts

@@ -1,63 +0,0 @@
-import { Document } from "mongoose";
-export interface ITrace extends Document {
-    traceId: string;
-    projectId: string;
-    meta?: TraceMetadata;
-    trace: Trace[];
-}
-/**
- * Node de las trazas
- */
-export interface Trace {
-    description: string;
-    traceId: string;
-    spanId: string;
-    parentSpanId: string;
-    projectId: string;
-    parentId?: number;
-    checkpoint: string;
-    function: string;
-    status: boolean;
-    type: "input" | "output";
-    startTime: number;
-    endTime?: number;
-    duration?: number;
-    inputData?: any;
-    outputData?: any;
-    additionalData?: any;
-    tags?: string[];
-    error?: {
-        message: string;
-        code?: string;
-        stack?: string;
-    };
-    source?: 'api' | 'web' | 'mobile' | 'cron' | 'system' | string;
-}
-export interface TraceMetadata {
-    userAgent: string | null;
-    environment: string | null;
-    platform: string | null;
-    ip: string | null;
-    user: {
-        id: string;
-        email: string;
-    } | null;
-    event: string;
-    url: string;
-    path: string;
-    route: string | null;
-    tags: string[];
-    browser: {
-        name: string | null;
-        version: string | null;
-    };
-    os: {
-        name: string | null;
-        version: string | null;
-    };
-    device: {
-        model: string | null;
-        type: string | null;
-        vendor: string | null;
-    };
-}

package/dist/types/types/traceSchema.d.ts

@@ -1,11 +0,0 @@
-import { Schema } from "@hemia/db-manager";
-import { ITrace } from "./traceModel";
-export declare const TraceSchema: Schema<ITrace, import("mongoose").Model<ITrace, any, any, any, import("mongoose").Document<unknown, any, ITrace, any, {}> & ITrace & Required<{
-    _id: unknown;
-}> & {
-    __v: number;
-}, any>, {}, {}, {}, {}, import("mongoose").DefaultSchemaOptions, ITrace, import("mongoose").Document<unknown, {}, import("mongoose").FlatRecord<ITrace>, {}, import("mongoose").ResolveSchemaOptions<import("mongoose").DefaultSchemaOptions>> & import("mongoose").FlatRecord<ITrace> & Required<{
-    _id: unknown;
-}> & {
-    __v: number;
-}>;