XPress Logger

XPress Logger is a versatile and powerful logging library for Node.js applications. It supports structured logging, data masking, custom log handling, and integration with observability tools like Elastic APM for enhanced performance monitoring and debugging.

Table of Contents

• Installation
• Getting Started
• Bootstrap Logger
• Transaction Spans
• Capture APM Middleware
• Write Log
• Examples

Installation

To install XPress Logger, use Yarn:

yarn add @sonatel/juf-xpress-logger

Set up your environment variables

# Only if you have an APM server to connect to
JUF_ELK_APM_SERVER="<JUF_ELK_APM_SERVER>"
JUF_ELK_APM_ENV_NAME="<JUF_ELK_APM_ENV_NAME>"
JUF_ELK_APM_SERVICE_NAME="<JUF_ELK_APM_SERVICE_NAME>"
JUF_ELK_APM_SECRET_TOKEN="<JUF_ELK_APM_SECRET_TOKEN>"

Getting Started

To start using XPress Logger, import the logger instance from the package. The logger is an instance of LoggerService which can be used to bootstrap the logger, manage transaction spans, capture APM middleware, and write logs.

import { logger } from 'osnmarket-xpress-logger';

// Bootstrap the logger with the desired configuration
logger.bootstrap({
  crypt: ['password', 'authorization'],
  logLevel: 'info',
  startApmAgent: true
});

Bootstrap Logger

The bootstrap method initializes the logger with the provided configuration. This is a necessary step to set up the logger before using its other functionalities.

Usage

logger.bootstrap({
  appName: 'MyApp',
  crypt: ['password', 'authorization'],
  logConsole: false,
  logDir: './logs',
  constantFileName: false,
  findLogFile: true,
  logLevel: 'info',
  startApmAgent: true
});

Parameters

• appName: (string) Application name for log identification.
• crypt: (Array< string >) List of keys to mask in the log data.
• logConsole: (boolean) Whether to log to the console by default it's activated.
• logDir: (string) Directory path to save log files if logConsole is false.
• constantFileName: (boolean) Whether to use a constant file name for logs.
• findLogFile: (Function) Function to determine a custom log action.
• logLevel: (string) Log level for APM configuration.
• startApmAgent: (boolean) Whether to start the APM agent.

Returns

• LoggerService: An instance of LoggerService.

Write Log

The writeLog method allows you to log structured information about requests, responses, or custom actions. You can log to the console or a file, and sensitive information can be masked.

Usage

logger.writeLog({
  params: {
    logFrom: '192.168.1.1',
    userIp: '10.0.0.1',
    method: 'POST',
    payload: { username: 'john_doe', password: 'secret' },
    headers: { 'user-agent': 'Mozilla/5.0' },
    logTarget: '/api/login',
    userAgent: 'Mozilla/5.0',
    logStatus: 200,
    logStatusCode: 'OK'
  },
  userName: 'john_doe',
  logLevel: 'INFO',
  action: 'User login',
  duration: 500
});

Parameters

• params: (object) Log parameters including request and response details.
  • logFrom: (string) The origin IP address of the log entry.
  • userIp: (string) The user’s IP address for the log entry.
  • method: (string) The HTTP method of the request (e.g., ‘GET’, ‘POST’).
  • payload: (Object|string) The request body content, can be an object or a stringified JSON.
  • headers: (Object|string) The request headers, can be an object or a stringified JSON.
  • logTarget: (string) The target URL of the log entry.
  • userAgent: (string) The User-Agent header string.
  • logStatus: (number) The HTTP status code of the response.
  • logStatusCode: (string) The HTTP status message (e.g., ‘OK’, ‘Not Found’).
• userName: (string) The username associated with the log entry.
• logLevel: (string) The log level (e.g., ‘INFO’, ‘ERROR’, ‘WARN’).
• action: (string) A brief description of the action being logged.
• duration: (number) Optional duration in milliseconds for how long the action took to complete.

Returns

• void
  • logs

{"@timestamp":"2024-09-04T13:12:07.376Z","ecs.version":"8.10.0","log.level":"info","meta":{"client.ip":"192.168.1.1","data_stream.type":"logs","event.action":"User login","event.category":"INFO","event.duration":500,"http.request.body.content":{"password":"secret","username":"john_doe"},"http.request.headers":{"user-agent":"Mozilla/5.0"},"http.request.method":"POST","http.response.status_code":200,"http.response.status_message":"OK","process.thread.id":78404,"source.name":"10.0.0.1","url.path":"/api/login","user.name":"john_doe","user_agent.original":"Mozilla/5.0"}}

Capture APM Middleware

The captureApmMiddleware method integrates with the Elastic APM to capture and monitor requests and responses for performance monitoring.

Usage

app.use((req, res, next) => {
  logger.captureApmMiddleware({
    params: {
      path: req.path,
      method: req.method,
      headers: req.headers,
      routeParams: req.params,
      queryParams: req.query,
      payload: req.body
    },
    callback: next,
    httpListener: {
      onFunction: res.on.bind(res),
      callback: () => console.log('Request completed')
    }
  });
  next();
});

Parameters

• params: (object) Parameters for the request.
  • path: (string) The path of the request.
  • method: (string) The HTTP method of the request.
  • headers: (object) The headers of the request.
  • routeParams: (object) The route parameters of the request.
  • queryParams: (object) The query parameters of the request.
  • payload: (object) The request payload.
• callback: (Function) Callback function after capture.
• httpListener: (object) HTTP listener functions.
• onFunction: (Function) Function that listens to HTTP events (e.g., ‘finish’).
• callback: (Function) Callback function to execute after the listener function.

Returns

• void

Transaction Spans

The transactionSpans property provides methods to manage transaction spans, which are useful for tracing specific actions and monitoring performance.

Usage

Start a new transaction span:

const span = logger.transactionSpans.begin({ 
  name: 'Database Query', 
  type: 'db',
  payload: { query: 'SELECT * FROM users' }  // Optional payload for context
});

// Perform some operations...

// End the transaction span
logger.transactionSpans.end(span);

Methods

• transactionSpans.begin(options): Starts a new transaction span.
• options.name: (string) The name of the span.
• options.type: (string, default: ‘external’) The type of the span (e.g., ‘db’, ‘external’).
• options.payload: (object) Optional payload for additional context.
• transactionSpans.end(span): Ends an existing transaction span.
• span: (object) The span object to be ended.

Returns

• begin: (object|null) Returns the created span object or null if creation fails.

Examples

Example 1: Bootstrap Logger and Write a Log Entry

logger.bootstrap({
  appName: 'MyApp',
  crypt: ['password', 'authorization']
});

logger.writeLog({
  params: {
    logFrom: '192.168.1.1',
    userIp: '10.0.0.1',
    method: 'POST',
    payload: { username: 'john_doe', password: 'secret' },
    headers: { 'user-agent': 'Mozilla/5.0' },
    logTarget: '/api/login',
    userAgent: 'Mozilla/5.0',
    logStatus: 200,
    logStatusCode: 'OK'
  },
  userName: 'john_doe',
  logLevel: 'INFO',
  action: 'User login',
  duration: 500
});

Example 2: Use Transaction Spans for Tracing

const span = logger.transactionSpans.begin({ 
  name: 'Database Query',
  type: 'db',
  payload: { query: 'SELECT * FROM users' }
});

// Perform some operations…

logger.transactionSpans.end(span);

Example 2: Use Transaction Spans for Tracing

const span = logger.transactionSpans.begin({ 
  name: 'Database Query',
  type: 'db',
  payload: { query: 'SELECT * FROM users' }
});

// Perform some operations…

logger.transactionSpans.end(span);

License

MIT License. See the LICENSE file for more information.

Feel free to expand on the README to reach out if any question occurs but first please >> RTM