pragma-log-manager-aws-lambda 1.0.0

package/README.es.md

@@ -0,0 +1,82 @@
+# Log Builder For AWS Lambda JS with OpenTelemetry And Winston
+
+## Descripción
+Una implementación de OpenTelemetry (OTEL) para Winston que proporciona trazabilidad para funciones AWS Lambda en Node.js.
+
+## Instalación
+
+```bash
+npm i pragma-log-manager-aws-lambda
+```
+
+## Requisitos
+Este paquete tiene las siguientes dependencias:
+- @opentelemetry/api: ^1.9.0
+- @opentelemetry/auto-instrumentations-node: ^0.52.0
+- @opentelemetry/exporter-trace-otlp-http: ^0.52.0
+- @opentelemetry/instrumentation-aws-lambda: ^0.52.0
+- @opentelemetry/resources: ^1.19.0
+- @opentelemetry/sdk-node: ^0.52.1
+- @opentelemetry/semantic-conventions: ^1.19.0
+- winston: ^3.17.0
+
+## Uso
+
+### Configuración básica
+
+```javascript
+import { logger, wrapLambdaHandler } from 'winston-otel-pragma-logs';
+
+// Función Lambda original
+const myHandler = async (event, context) => {
+  // Registrar un mensaje con información de trazabilidad
+  logger.info('Procesando evento', { action: { eventData: event } });
+  
+  // Tu lógica de negocio aquí
+  const result = await procesarDatos(event);
+  
+  logger.info('Procesamiento completado', { action: { resultado: result } });
+  return result;
+};
+
+// Exportar el handler envuelto con trazabilidad
+export const handler = wrapLambdaHandler(myHandler);
+```
+
+### Configuración de variables de entorno
+
+El paquete utiliza las siguientes variables de entorno:
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: URL del endpoint para exportar trazas OTLP (por ejemplo, "https://api.honeycomb.io/v1/traces")
+- `OTEL_SERVICE_NAME`: Nombre del servicio para identificar tu aplicación en las trazas (por defecto: "default-lambda")
+
+## Formato de logs
+
+Los logs generados incluyen automáticamente información de trazabilidad en formato JSON:
+
+```json
+{
+  "timestamp": "2023-06-15T12:34:56.789Z",
+  "tracing": {
+    "traceId": "abcdef1234567890abcdef1234567890",
+    "spanId": "abcdef1234567890"
+  },
+  "level": "info",
+  "message": "Mensaje de log",
+  "data": {
+    "clave": "valor",
+    "otrosDatos": 123
+  }
+}
+```
+
+## Características
+
+- Integración automática de Winston con OpenTelemetry
+- Wrapper para funciones Lambda que crea spans automáticamente
+- Correlación automática entre logs y trazas
+- Instrumentación automática para AWS Lambda y otras bibliotecas de Node.js
+- Exportación de trazas a cualquier backend compatible con OTLP
+
+## Licencia
+Desarrollado por [juan.ojeda@pragma.com.co](mailto:juan.ojeda@pragma.com.co)

package/README.md

@@ -0,0 +1,85 @@
+# winston-otel-pragma-logs
+
+## Description
+An OpenTelemetry (OTEL) implementation for Winston that provides tracing for AWS Lambda functions in Node.js.
+
+## Installation
+
+```bash
+npm i pragma-log-manager-aws-lambda
+```
+
+## Requirements
+This package has the following peer dependencies:
+- @opentelemetry/api: ^1.9.0
+- @opentelemetry/auto-instrumentations-node: ^0.52.0
+- @opentelemetry/exporter-trace-otlp-http: ^0.52.0
+- @opentelemetry/instrumentation-aws-lambda: ^0.52.0
+- @opentelemetry/resources: ^1.19.0
+- @opentelemetry/sdk-node: ^0.52.1
+- @opentelemetry/semantic-conventions: ^1.19.0
+- winston: ^3.17.0
+
+## Usage
+
+### Basic Configuration
+
+```javascript
+import { logger, wrapLambdaHandler } from 'winston-otel-pragma-logs';
+
+// Original Lambda function
+const myHandler = async (event, context) => {
+  // Log a message with tracing information
+  logger.info('Processing event', { action: { eventData: event } });
+  
+  // Your business logic here
+  const result = await processData(event);
+  
+  logger.info('Processing completed', { action: { result: result } });
+  return result;
+};
+
+// Export the wrapped handler with tracing
+export const handler = wrapLambdaHandler(myHandler);
+```
+
+### Environment Variables Configuration
+
+The package uses the following environment variables:
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: URL of the endpoint to export OTLP traces (e.g., "https://api.honeycomb.io/v1/traces")
+- `OTEL_SERVICE_NAME`: Service name to identify your application in traces (default: "default-lambda")
+
+## Log Format
+
+The generated logs automatically include tracing information in JSON format:
+
+```json
+{
+  "timestamp": "2023-06-15T12:34:56.789Z",
+  "tracing": {
+    "traceId": "abcdef1234567890abcdef1234567890",
+    "spanId": "abcdef1234567890"
+  },
+  "level": "info",
+  "message": "Log message",
+  "data": {
+    "key": "value",
+    "otherData": 123
+  }
+}
+```
+
+## Features
+
+- Automatic integration of Winston with OpenTelemetry
+- Wrapper for Lambda functions that automatically creates spans
+- Automatic correlation between logs and traces
+- Automatic instrumentation for AWS Lambda and other Node.js libraries
+- Export traces to any OTLP-compatible backend
+
+## Spanish Documentation
+For Spanish documentation, please see [README.es.md](README.es.md).
+
+## License
+Developed by [juan.ojeda@pragma.com.co](mailto:juan.ojeda@pragma.com.co)

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export * from './logger';
+export * from './wrapper';

package/dist/cjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger"), exports);
+__exportStar(require("./wrapper"), exports);

package/dist/cjs/logger.d.ts

@@ -0,0 +1,3 @@
+import * as winston from "winston";
+import './tracing';
+export declare const logger: winston.Logger;

package/dist/cjs/logger.js

@@ -0,0 +1,67 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const winston = __importStar(require("winston"));
+const moment = __importStar(require("moment-timezone"));
+require("./tracing");
+const tracing_1 = require("./tracing");
+exports.logger = winston.createLogger({
+    level: 'info',
+    format: winston.format.combine(winston.format.timestamp({
+        format: () => moment.tz('America/Bogota').format('YYYY-MM-DDTHH:mm:ss.SSS')
+    }), winston.format.printf(({ level, message, timestamp, ...obj }) => {
+        const { traceId, spanId } = (0, tracing_1.getCurrentTrace)();
+        const payload = obj.action;
+        const error = obj.error;
+        const transactionId = obj.transactionId;
+        const log = {
+            timestamp,
+            severity: level,
+            transactionId: transactionId ?? 'Id Not Available',
+            message,
+            appName: process.env.OTEL_SERVICE_NAME,
+            appNamespace: process.env.OTEL_SERVICE_NAMESPACE ?? 'namespaceTest',
+            tracing: {
+                traceId,
+                spanId
+            },
+            action: payload,
+            error: error
+        };
+        return JSON.stringify(log);
+    })),
+    transports: [new winston.transports.Console()],
+});

package/dist/cjs/tracing.d.ts

@@ -0,0 +1,5 @@
+export declare const tracer: import("@opentelemetry/api").Tracer;
+export declare const getCurrentTrace: () => {
+    traceId: string;
+    spanId: string;
+};

package/dist/cjs/tracing.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentTrace = exports.tracer = void 0;
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const instrumentation_aws_lambda_1 = require("@opentelemetry/instrumentation-aws-lambda");
+const api_1 = require("@opentelemetry/api");
+let sdk = null;
+const initializeSDK = () => {
+    if (sdk)
+        return sdk;
+    const traceExporter = process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+        ? new exporter_trace_otlp_http_1.OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT })
+        : undefined;
+    sdk = new sdk_node_1.NodeSDK({
+        resource: new resources_1.Resource({
+            [semantic_conventions_1.ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || 'default-lambda',
+        }),
+        instrumentations: [
+            new instrumentation_aws_lambda_1.AwsLambdaInstrumentation()
+        ],
+        traceExporter: traceExporter
+    });
+    sdk.start();
+    return sdk;
+};
+// Initialize SDK
+initializeSDK();
+exports.tracer = api_1.trace.getTracer('default-tracer');
+const getCurrentTrace = () => {
+    const activeSpan = api_1.trace.getActiveSpan();
+    if (!activeSpan) {
+        return {
+            traceId: 'no-trace-id',
+            spanId: 'no-span-id'
+        };
+    }
+    const spanContext = activeSpan.spanContext();
+    return {
+        traceId: spanContext.traceId,
+        spanId: spanContext.spanId
+    };
+};
+exports.getCurrentTrace = getCurrentTrace;
+process.on('SIGTERM', () => {
+    if (sdk) {
+        sdk.shutdown().then();
+    }
+});

package/dist/cjs/wrapper.d.ts

@@ -0,0 +1,2 @@
+import { Context } from 'aws-lambda';
+export declare const wrapLambdaHandler: (handlerFunction: Function) => (event: any, context: Context) => Promise<any>;

package/dist/cjs/wrapper.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapLambdaHandler = void 0;
+const tracing_1 = require("./tracing");
+const wrapLambdaHandler = (handlerFunction) => {
+    return async (event, context) => {
+        return tracing_1.tracer.startActiveSpan('lambda-execution', async (span) => {
+            try {
+                const result = await handlerFunction(event, context);
+                span.end();
+                return result;
+            }
+            catch (error) {
+                span.recordException(error);
+                span.end();
+                throw error;
+            }
+        });
+    };
+};
+exports.wrapLambdaHandler = wrapLambdaHandler;

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './logger';
+export * from './wrapper';

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export * from './logger';
+export * from './wrapper';

package/dist/esm/logger.d.ts

@@ -0,0 +1,3 @@
+import * as winston from "winston";
+import './tracing';
+export declare const logger: winston.Logger;

package/dist/esm/logger.js

@@ -0,0 +1,31 @@
+import * as winston from "winston";
+import * as moment from "moment-timezone";
+import './tracing';
+import { getCurrentTrace } from "./tracing";
+export const logger = winston.createLogger({
+    level: 'info',
+    format: winston.format.combine(winston.format.timestamp({
+        format: () => moment.tz('America/Bogota').format('YYYY-MM-DDTHH:mm:ss.SSS')
+    }), winston.format.printf(({ level, message, timestamp, ...obj }) => {
+        const { traceId, spanId } = getCurrentTrace();
+        const payload = obj.action;
+        const error = obj.error;
+        const transactionId = obj.transactionId;
+        const log = {
+            timestamp,
+            severity: level,
+            transactionId: transactionId ?? 'Id Not Available',
+            message,
+            appName: process.env.OTEL_SERVICE_NAME,
+            appNamespace: process.env.OTEL_SERVICE_NAMESPACE ?? 'namespaceTest',
+            tracing: {
+                traceId,
+                spanId
+            },
+            action: payload,
+            error: error
+        };
+        return JSON.stringify(log);
+    })),
+    transports: [new winston.transports.Console()],
+});

package/dist/esm/tracing.d.ts

@@ -0,0 +1,5 @@
+export declare const tracer: import("@opentelemetry/api").Tracer;
+export declare const getCurrentTrace: () => {
+    traceId: string;
+    spanId: string;
+};

package/dist/esm/tracing.js

@@ -0,0 +1,47 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { Resource } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { AwsLambdaInstrumentation } from '@opentelemetry/instrumentation-aws-lambda';
+import { trace } from '@opentelemetry/api';
+let sdk = null;
+const initializeSDK = () => {
+    if (sdk)
+        return sdk;
+    const traceExporter = process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+        ? new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT })
+        : undefined;
+    sdk = new NodeSDK({
+        resource: new Resource({
+            [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || 'default-lambda',
+        }),
+        instrumentations: [
+            new AwsLambdaInstrumentation()
+        ],
+        traceExporter: traceExporter
+    });
+    sdk.start();
+    return sdk;
+};
+// Initialize SDK
+initializeSDK();
+export const tracer = trace.getTracer('default-tracer');
+export const getCurrentTrace = () => {
+    const activeSpan = trace.getActiveSpan();
+    if (!activeSpan) {
+        return {
+            traceId: 'no-trace-id',
+            spanId: 'no-span-id'
+        };
+    }
+    const spanContext = activeSpan.spanContext();
+    return {
+        traceId: spanContext.traceId,
+        spanId: spanContext.spanId
+    };
+};
+process.on('SIGTERM', () => {
+    if (sdk) {
+        sdk.shutdown().then();
+    }
+});

package/dist/esm/wrapper.d.ts

@@ -0,0 +1,2 @@
+import { Context } from 'aws-lambda';
+export declare const wrapLambdaHandler: (handlerFunction: Function) => (event: any, context: Context) => Promise<any>;

package/dist/esm/wrapper.js

@@ -0,0 +1,17 @@
+import { tracer } from './tracing';
+export const wrapLambdaHandler = (handlerFunction) => {
+    return async (event, context) => {
+        return tracer.startActiveSpan('lambda-execution', async (span) => {
+            try {
+                const result = await handlerFunction(event, context);
+                span.end();
+                return result;
+            }
+            catch (error) {
+                span.recordException(error);
+                span.end();
+                throw error;
+            }
+        });
+    };
+};

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './logger';
+export * from './wrapper';

package/dist/types/logger.d.ts

@@ -0,0 +1,3 @@
+import * as winston from "winston";
+import './tracing';
+export declare const logger: winston.Logger;

package/dist/types/tracing.d.ts

@@ -0,0 +1,5 @@
+export declare const tracer: import("@opentelemetry/api").Tracer;
+export declare const getCurrentTrace: () => {
+    traceId: string;
+    spanId: string;
+};

package/dist/types/wrapper.d.ts

@@ -0,0 +1,2 @@
+import { Context } from 'aws-lambda';
+export declare const wrapLambdaHandler: (handlerFunction: Function) => (event: any, context: Context) => Promise<any>;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pragma-log-manager-aws-lambda",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "description": "OTEL - Winston implementation tracing for aws node lambdas in js",
+  "author": "juan.ojeda@pragma.com.co",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:types": "tsc --project tsconfig.types.json"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.52.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
+    "@opentelemetry/instrumentation-aws-lambda": "^0.52.0",
+    "@opentelemetry/resources": "^1.19.0",
+    "@opentelemetry/sdk-node": "^0.52.1",
+    "@opentelemetry/semantic-conventions": "^1.19.0",
+    "winston": "^3.17.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "moment-timezone": "^0.6.0"
+  },
+  "overrides": {
+    "protobufjs": "^7.5.5"
+  },
+  "resolutions": {
+    "protobufjs": "^7.5.5"
+  }
+}