@hemia/trace-manager 0.0.3 → 0.0.5

package/README.md

@@ -33,11 +33,12 @@ Instrumenta automáticamente métodos creando spans de OpenTelemetry con captura
 #### **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`
+- 🔹 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
 
 #### **Uso básico:**
 
@@ -48,10 +49,10 @@ 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
+    // - 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;
@@ -329,25 +330,171 @@ Y múltiples logs correlacionados con el mismo `TraceId`.
 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
+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
 
 ---
 
 ## 🛠️ 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 internas que previenen:
+Utilidades legacy que previenen:
 - Serialización de objetos circulares
-- Exposición de contraseñas/tokens en atributos
+- 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` - Manejo de contexto con AsyncLocalStorage
-- `uuid` - Generación de IDs únicos para spans
+- `@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)
 
 ---
 

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=i.spanId,p=this?.constructor?.name||r.name||"UnknownClass",d=e?.name||`${p}.${n}`,l=process.hrtime.bigint(),f={Timestamp:(new Date).toISOString(),TraceId:i.traceId,SpanId:a,ParentSpanId:c,TraceState:"",ServiceName:i.serviceName,SpanName:d,SpanKind:e?.kind||"SPAN_KIND_INTERNAL",DurationUInt64:BigInt(0),StatusCode:"STATUS_CODE_UNSET",StatusMessage:"",SpanAttributes:{"code.function":n,"code.namespace":p,...e?.attributes},ResourceAttributes:i.traceContext.resourceAttributes,EventsNested:[],LinksNested:[]},S={...i,spanId:a};return t.run(S,async()=>{try{g(f.SpanAttributes,o);const t=await s.apply(this,o);return y(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,"exception.stacktrace":String(t.stack||"").substring(0,1e3)}};throw f.EventsNested.push(e),f.StatusCode="STATUS_CODE_ERROR",f.StatusMessage=t.message,t}finally{const t=process.hrtime.bigint();f.DurationUInt64=t-l,i.traceContext.spans.push(f)}})}}}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 o=new class{constructor(t){this.defaultServiceName=t}log(t,o,n){const s=e.asyncContext.getStore();if(!s)return console.warn("[Logger] No active context. Log not traced."),void console.log(`[${t}] ${o}`,n);const a={Timestamp:(new Date).toISOString(),TraceId:s.traceId,SpanId:s.spanId,TraceFlags:1,SeverityText:t,SeverityNumber:r[t],ServiceName:s.serviceName,Body:o,LogAttributes:this.stringifyAttributes(n||{}),ResourceAttributes:s.traceContext.resourceAttributes};s.traceContext.logs.push(a),"production"!==process.env.NODE_ENV&&console.log(`[${t}] [TraceId:${s.traceId.substring(0,8)}...] ${o}`,n||"")}stringifyAttributes(t){const e={};for(const[r,o]of Object.entries(t))if(null==o)e[r]="";else if("string"==typeof o)e[r]=o;else try{e[r]=JSON.stringify(o)}catch{e[r]=String(o)}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 n,s=[],a=0;a<256;++a)s.push((a+256).toString(16).slice(1));var i=new Uint8Array(16);function c(){if(!n&&!(n="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 n(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 o=(t=t||{}).random||(t.rng||c)();return o[6]=15&o[6]|64,o[8]=63&o[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()}(o)}function g(t,e){t["app.method.args.count"]=e.length.toString(),t["app.method.args.types"]=e.map(t=>typeof t).join(",")}function d(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,o,n){const s=n?.value;if("function"!=typeof s)throw new Error("@Trace can only be applied to methods");n.value=async function(...n){const a=e.asyncContext.getStore();if(!a)return console.warn("[Trace] No active context. Skipping trace."),await s.apply(this,n);const i=u(),c=a.spanId,p=this?.constructor?.name||r.name||"UnknownClass",y=t?.name||`${p}.${o}`,l=process.hrtime.bigint(),S={Timestamp:(new Date).toISOString(),TraceId:a.traceId,SpanId:i,ParentSpanId:c,TraceState:"",ServiceName:a.serviceName,SpanName:y,SpanKind:t?.kind||"SPAN_KIND_INTERNAL",DurationUInt64:BigInt(0),StatusCode:"STATUS_CODE_UNSET",StatusMessage:"",SpanAttributes:{"code.function":o,"code.namespace":p,...t?.attributes},ResourceAttributes:a.traceContext.resourceAttributes,EventsNested:[],LinksNested:[]},f={...a,spanId:i};return e.asyncContext.run(f,async()=>{try{g(S.SpanAttributes,n);const t=await s.apply(this,n);return d(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,"exception.stacktrace":String(t.stack||"").substring(0,1e3)}};throw S.EventsNested.push(e),S.StatusCode="STATUS_CODE_ERROR",S.StatusMessage=t.message,t}finally{const t=process.hrtime.bigint();S.DurationUInt64=t-l,a.traceContext.spans.push(S)}})}}},exports.addArgsMetadata=g,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 o=Object.keys(e);t[`${r}.keys`]=o.join(","),t[`${r}.keyCount`]=o.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 o=Object.keys(e);t[`${r}.keys`]=o.join(","),t[`${r}.keyCount`]=o.length.toString()}Array.isArray(e)&&(t[`${r}.isArray`]="true",t[`${r}.length`]=e.length.toString())},exports.addResponseBodyMetadata=function(t,e,r=!1,o="http.response.body"){if(t[`${o}.exists`]=(!!e).toString(),t[`${o}.type`]=typeof e,e&&"object"==typeof e){const r=Object.keys(e);t[`${o}.keys`]=r.join(","),t[`${o}.keyCount`]=r.length.toString()}Array.isArray(e)&&(t[`${o}.isArray`]="true",t[`${o}.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=d,exports.logger=o;

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

@@ -4,3 +4,9 @@ import { TraceOptions } from "../types/traceOptions";
  * 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;
+/**
+ * Aplica @Trace automáticamente a todos los métodos de la clase
+ */
+export declare function Traceable(options?: {
+    exclude?: string[];
+}): (constructor: Function) => void;

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.3",
+  "version": "0.0.5",
   "description": "Gestor de trazas para registrar logs, errores y evento",
   "main": "dist/hemia-trace-manager.js",
   "module": "dist/hemia-trace-manager.esm.js",
@@ -13,7 +13,7 @@
     "test": "jest --passWithNoTests --detectOpenHandles"
   },
   "devDependencies": {
-    "@hemia/app-context": "^0.0.3",
+    "@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",