azify-logger 1.0.5 → 1.0.9

package/README.md

@@ -8,7 +8,7 @@ Sistema de logging centralizado com OpenTelemetry e OpenSearch para múltiplas a
 
 | Ambiente | URL                                                   |
 |----------|-------------------------------------------------------|
-| **Development** | `http://localhost:3001`                               |
+| **Development** | `http://localhost:3001/log`                           |
 | **Staging** | `https://logsdashboard.azify.dev/send`                |
 | **Production** | `https://logsdashboard.azify.prd/send` (a configurar) |
 
@@ -82,20 +82,20 @@ const app = express()
 
 ## ⚙️ Variáveis de Ambiente
 
-| Variável | Padrão | Descrição |
-|----------|-------|-----------|
-| `APP_NAME` | - | Nome da aplicação |
-| `AZIFY_LOGGER_URL` | `http://localhost:3001` | URL do logger |
+| Variável | Padrão                            | Descrição |
+|----------|-----------------------------------|-----------|
+| `APP_NAME` | -                                 | Nome da aplicação |
+| `AZIFY_LOGGER_URL` | `http://localhost:3001/log`       | URL do logger |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` | OTLP endpoint |
-| `NODE_ENV` | `development` | Ambiente |
-| `AZIFY_LOGGER_AUTOREG_DISABLE` | `""` | Se `"1"`, desativa auto-registro do OTEL |
+| `NODE_ENV` | `development`                     | Ambiente |
+| `AZIFY_LOGGER_AUTOREG_DISABLE` | `""`                              | Se `"1"`, desativa auto-registro do OTEL |
 
 ### 🌐 URLs por Ambiente
 
 **Desenvolvimento (Local):**
 ```env
 APP_NAME=minha-app
-AZIFY_LOGGER_URL=http://localhost:3001
+AZIFY_LOGGER_URL=http://localhost:3001/log
 NODE_ENV=development
 ```
 
@@ -118,7 +118,7 @@ NODE_ENV=production
 Apenas se estiver usando Docker Compose com rede compartilhada:
 
 ```env
-AZIFY_LOGGER_URL=http://azify-logger:3001
+AZIFY_LOGGER_URL=http://azify-logger:3001/log
 ```
 
 ### Docker e Node antigos
@@ -165,7 +165,7 @@ if (createAzifyBunyanStream) {
     level: 'info',
     type: 'raw',
     stream: createAzifyBunyanStream({
-      loggerUrl: process.env.AZIFY_LOGGER_URL || 'http://localhost:3001',
+      loggerUrl: process.env.AZIFY_LOGGER_URL || 'http://localhost:3001/log',
       serviceName: process.env.APP_NAME || 'app'
     })
   })
@@ -193,7 +193,7 @@ const { streams } = require('azify-logger')
 const pino = require('pino')
 
 const logger = pino({ level: 'info' }, streams.createPinoStream({
-  loggerUrl: 'http://localhost:3001',
+  loggerUrl: 'http://localhost:3001/log',
   serviceName: 'nome-app'
 }))
 
@@ -207,7 +207,7 @@ const { createAzifyLogger } = require('azify-logger')
 
 const logger = createAzifyLogger({
   serviceName: 'nome-app',
-  loggerUrl: 'http://localhost:3001'
+  loggerUrl: 'http://localhost:3001/log'
 })
 
 logger.info('Mensagem', { userId: '123' })
@@ -232,7 +232,7 @@ Aguarde alguns minutos. Você verá:
 ✅ Tudo pronto!
 📊 OpenSearch: http://localhost:9200
 🎨 OpenSearch Dashboards: http://localhost:5601
-📝 Logger API: http://localhost:3001
+📝 Logger API: http://localhost:3001/log
 🔭 OTEL Collector: http://localhost:4318
 ```
 

package/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * AzifyLogger class for structured logging with OpenTelemetry integration
+ */
+export class AzifyLogger {
+  /**
+   * Creates an instance of AzifyLogger
+   * @param options - Configuration options
+   */
+  constructor(options?: {
+    serviceName?: string;
+    loggerUrl?: string;
+    environment?: string;
+  });
+
+  /**
+   * Sends a log entry to the azify-logger service
+   * @param level - Log level (info, error, warn, debug)
+   * @param message - Log message
+   * @param meta - Additional metadata to include in the log
+   */
+  log(level: string, message: string, meta?: Record<string, any>): Promise<void>;
+
+  /**
+   * Logs an info level message
+   * @param message - Log message
+   * @param meta - Additional metadata
+   */
+  info(message: string, meta?: Record<string, any>): Promise<void>;
+
+  /**
+   * Logs an error level message with optional error object
+   * @param message - Log message
+   * @param error - Error object to include in metadata
+   * @param meta - Additional metadata
+   */
+  error(message: string, error?: Error | null, meta?: Record<string, any>): Promise<void>;
+
+  /**
+   * Logs a warning level message
+   * @param message - Log message
+   * @param meta - Additional metadata
+   */
+  warn(message: string, meta?: Record<string, any>): Promise<void>;
+
+  /**
+   * Logs a debug level message
+   * @param message - Log message
+   * @param meta - Additional metadata
+   */
+  debug(message: string, meta?: Record<string, any>): Promise<void>;
+}
+
+/**
+ * Creates a new AzifyLogger instance with custom options
+ * @param options - Configuration options
+ * @returns New AzifyLogger instance
+ */
+export function createAzifyLogger(options?: {
+  serviceName?: string;
+  loggerUrl?: string;
+  environment?: string;
+}): AzifyLogger;
+
+/**
+ * Creates a new AzifyLogger instance using environment variables
+ * @returns New AzifyLogger instance configured from environment
+ */
+export function createAzifyLoggerFromEnv(): AzifyLogger;
+
+/**
+ * Streams for different logging libraries
+ */
+export const streams: {
+  createBunyanStream: any;
+  createPinoStream: any;
+};
+
+/**
+ * Middleware for different frameworks
+ */
+export const middleware: {
+  restify: any;
+  express: () => any;
+};
+
+export default AzifyLogger;

package/index.js

@@ -8,7 +8,18 @@ if (process.env.AZIFY_LOGGER_AUTOREG_DISABLE !== '1') {
   try { require('./register-restify') } catch (_) {}
 }
 
+/**
+ * AzifyLogger class for structured logging with OpenTelemetry integration
+ * @class
+ */
 class AzifyLogger {
+  /**
+   * Creates an instance of AzifyLogger
+   * @param {Object} options - Configuration options
+   * @param {string} [options.serviceName='azipay'] - Name of the service
+   * @param {string} [options.loggerUrl='http://localhost:3001'] - URL of the azify-logger service
+   * @param {string} [options.environment] - Environment name (defaults to NODE_ENV or 'development')
+   */
   constructor(options = {}) {
     this.options = {
       serviceName: options.serviceName || 'azipay',
@@ -21,6 +32,13 @@ class AzifyLogger {
     propagation.setGlobalPropagator(this.propagator)
   }
 
+  /**
+   * Sends a log entry to the azify-logger service
+   * @param {string} level - Log level (info, error, warn, debug)
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata to include in the log
+   * @returns {Promise<void>}
+   */
   async log(level, message, meta = {}) {
     const span = trace.getSpan(context.active())
     const spanContext = span?.spanContext()
@@ -64,10 +82,23 @@ class AzifyLogger {
     }
   }
 
+  /**
+   * Logs an info level message
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {Promise<void>}
+   */
   info(message, meta = {}) {
     return this.log('info', message, meta)
   }
 
+  /**
+   * Logs an error level message with optional error object
+   * @param {string} message - Log message
+   * @param {Error} [error=null] - Error object to include in metadata
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {Promise<void>}
+   */
   error(message, error = null, meta = {}) {
     const logMeta = { ...meta }
     if (error) {
@@ -80,19 +111,49 @@ class AzifyLogger {
     return this.log('error', message, logMeta)
   }
 
+  /**
+   * Logs a warning level message
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {Promise<void>}
+   */
   warn(message, meta = {}) {
     return this.log('warn', message, meta)
   }
 
+  /**
+   * Logs a debug level message
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata
+   * @returns {Promise<void>}
+   */
   debug(message, meta = {}) {
     return this.log('debug', message, meta)
   }
 }
 
+/**
+ * Creates a new AzifyLogger instance with custom options
+ * @param {Object} options - Configuration options
+ * @param {string} [options.serviceName] - Name of the service
+ * @param {string} [options.loggerUrl] - URL of the azify-logger service
+ * @param {string} [options.environment] - Environment name
+ * @returns {AzifyLogger} New AzifyLogger instance
+ * @example
+ * const logger = createAzifyLogger({ serviceName: 'my-app' });
+ * logger.info('Hello world');
+ */
 function createAzifyLogger(options = {}) {
   return new AzifyLogger(options)
 }
 
+/**
+ * Creates a new AzifyLogger instance using environment variables
+ * @returns {AzifyLogger} New AzifyLogger instance configured from environment
+ * @example
+ * const logger = createAzifyLoggerFromEnv();
+ * logger.info('Hello world');
+ */
 function createAzifyLoggerFromEnv() {
   return createAzifyLogger({
     serviceName: process.env.APP_NAME || 'azipay',

package/middleware-express.js

@@ -1,6 +1,17 @@
 const axios = require('axios')
 const { als, runWithRequestContext, startRequestContext, getRequestContext } = require('./store')
 
+/**
+ * Creates an Express middleware for automatic request/response logging with azify-logger
+ * @param {Object} options - Configuration options
+ * @param {string} [options.serviceName] - Name of the service (defaults to APP_NAME env var or 'assemble')
+ * @param {string} [options.loggerUrl] - URL of the azify-logger service (defaults to AZIFY_LOGGER_URL env var or 'http://localhost:3001')
+ * @param {string} [options.environment] - Environment name (defaults to NODE_ENV env var or 'development')
+ * @returns {Function} Express middleware function
+ * @example
+ * const azifyMiddleware = require('azify-logger/middleware-express');
+ * app.use(azifyMiddleware({ serviceName: 'my-app' }));
+ */
 function createExpressLoggingMiddleware(options = {}) {
   const config = {
     serviceName: options.serviceName || process.env.APP_NAME || 'assemble',
@@ -8,6 +19,13 @@ function createExpressLoggingMiddleware(options = {}) {
     environment: options.environment || process.env.NODE_ENV || 'development'
   }
 
+  /**
+   * Sends a log entry to the azify-logger service
+   * @param {string} level - Log level (info, error, warn, debug)
+   * @param {string} message - Log message
+   * @param {Object} [meta={}] - Additional metadata to include in the log
+   * @private
+   */
   async function sendLog(level, message, meta = {}) {
     const logData = {
       level,
@@ -33,6 +51,13 @@ function createExpressLoggingMiddleware(options = {}) {
     }
   }
 
+  /**
+   * Express middleware function that logs requests and responses
+   * @param {Object} req - Express request object
+   * @param {Object} res - Express response object  
+   * @param {Function} next - Express next function
+   * @returns {void}
+   */
   return function azifyExpressLoggingMiddleware(req, res, next) {
     const startTime = Date.now()
     const requestId = req.requestId || require('uuid').v4()
@@ -206,6 +231,10 @@ function createExpressLoggingMiddleware(options = {}) {
       originalEnd.call(this, chunk, encoding)
     }
     
+    /**
+     * Logs the response data to azify-logger
+     * @private
+     */
     function logResponse() {
       const duration = Date.now() - startTime
       

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "azify-logger",
-  "version": "1.0.5",
+  "version": "1.0.9",
   "description": "Azify Logger Client - Centralized logging for OpenSearch",
   "main": "index.js",
+  "types": "index.d.ts",
   "type": "commonjs",
   "scripts": {
     "test": "echo \"No tests specified\" && exit 0",
@@ -47,6 +48,7 @@
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "store.js",
     "register-otel.js",
     "register-restify.js",

package/server.js

@@ -32,6 +32,11 @@ const propagator = new W3CTraceContextPropagator()
 
 const traceContextMap = new Map()
 
+/**
+ * Ensures the OpenSearch index exists and is properly configured
+ * @returns {Promise<void>}
+ * @private
+ */
 async function ensureIndex() {
   const indexName = 'logs-azify'
   const osUrl = process.env.OPENSEARCH_URL || 'http://localhost:9200'