logging-audit-utils/README.md

A comprehensive logging and audit utility with support for dynamic attributes and audit logging

# logging-audit-utils

[![npm version](https://badge.fury.io/js/logging-audit-utils.svg)](https://badge.fury.io/js/logging-audit-utils)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D12.0.0-brightgreen.svg)](https://nodejs.org/)
[![npm](https://img.shields.io/npm/dt/logging-audit-utils.svg)](https://www.npmjs.com/package/logging-audit-utils)

A comprehensive logging and audit utility for Node.js applications that provides structured logging with Winston and audit logging capabilities. This utility helps in maintaining consistent logging patterns and audit trails across applications.

## Table of Contents

- [Quick Start](#quick-start)
- [Why logging-audit-utils?](#why-logging-audit-utils)
- [Features](#features)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Migration Guide](#migration-guide)
- [Troubleshooting](#troubleshooting)
- [Requirements](#requirements)
- [Best Practices](#best-practices)
- [Contributing](#contributing)
- [License](#license)
- [Author](#author)
- [Support](#support)

## Quick Start

```bash
npm install logging-audit-utils
```

```javascript
const { Logger, AuditLogger, Statuses } = require('logging-audit-utils');

// Create logger with optional attributes
const logger = Logger.getLogger('handler', 'corr-123', {
    partner: 'partner',
    customer: 'customer'
}, {
    name: 'name',
    environment: 'production',
    serviceName: 'auth-service',
    customField: 'value'
});

// Basic logging
logger.info('User logged in');
logger.error('Error occurred', { error: new Error('Something went wrong') });

// Audit logging
const auditLogger = new AuditLogger.Builder(logger)
    .withStepCategory('invocation')
    .withEntity('user')
    .withStepStatus(Statuses.ENTITY.STARTED)
    .withRecordAuditFlag(true)
    .withProjectCode('project-code')
    .build();

auditLogger.generateAuditlog();
```

## Why logging-audit-utils?

- **Consistent Logging**: Enforces a standard logging format across your entire application
- **Audit Trail**: Built-in support for audit logging with mandatory attributes
- **Dynamic Attributes**: Flexible attribute system that adapts to your needs
- **Correlation**: Easy request tracing with correlation IDs
- **Security**: Built-in support for handling sensitive data
- **Production Ready**: Battle-tested in production environments
- **Zero Configuration**: Works out of the box with sensible defaults

## Features

- 📝 Structured logging using Winston
- 🔍 Audit logging with mandatory and optional attributes
- 🔗 Support for correlation IDs and request tracing
- 🎯 Dynamic attribute management
- 🔒 Sensitive data handling
- ⚙️ Configurable log levels
- 🌍 Support for different environments

## API Reference

### Logger

```javascript
Logger.getLogger(filename, correlationId, identities, optionalAttributes)
```

Parameters:
- `filename`: Name of the file/module
- `correlationId`: Unique identifier for request tracing
- `identities`: Object containing customer and partner information
- `optionalAttributes`: (Optional) Additional attributes included in every log message

Example:
```javascript
const logger = Logger.getLogger('handler', 'corr-123', {
    partner: 'partner',
    customer: 'customer'
}, {
    name: 'name',
    environment: 'production',
    serviceName: 'auth-service',
    customField: 'value'
});
```

### AuditLogger

```javascript
new AuditLogger.Builder(logger)
    .withStepCategory(category)
    .withEntity(entity)
    .withStepStatus(status)
    .withRecordAuditFlag(true)
    .withProjectCode(code)
    .build()
```

Mandatory attributes when `recordAuditFlag` is true:
- `projectCode`
- `component`
- Either `partner` and `customer` or `clientId`

### Statuses

```javascript
const { Statuses } = require('logging-audit-utils');

// Available statuses
Statuses.ENTITY.STARTED
Statuses.ENTITY.SUCCESS
Statuses.ENTITY.FAILED
Statuses.WORKFLOW.STARTED
Statuses.WORKFLOW.COMPLETED
Statuses.WORKFLOW.FAILED
```

## Configuration

### Environment Variables

- `LOG_LEVEL`: Set logging level (default: 'info')
- `COMPONENT`: Set component name

### Log Levels

- `error`: Error conditions
- `warn`: Warning conditions
- `info`: Informational messages
- `debug`: Debug messages

## Migration Guide

### From Winston

If you're currently using Winston directly, migration is straightforward:

```javascript
// Before
const winston = require('winston');
const logger = winston.createLogger({...});

// After
const { Logger } = require('logging-audit-utils');
const logger = Logger.getLogger('filename', 'corr-123', {
    partner: 'partner',
    customer: 'customer'
});
```

### From Other Logging Libraries

1. Replace your existing logger initialization with `Logger.getLogger()`
2. Add correlation ID to your logging calls
3. Use the audit logger for audit-related logging
4. Update your log format to match the new structure

## Troubleshooting

### Common Issues

1. **Missing Mandatory Attributes**
   ```
   Error: Setting recordAuditFlag=true, requires mandatory attributes: [projectCode, component]
   ```
   Solution: Ensure all required attributes are set when using `recordAuditFlag`

2. **Logger Not Initialized**
   ```
   Error: Missing Logger
   ```
   Solution: Always provide a logger instance to AuditLogger.Builder

3. **Correlation ID Issues**
   ```
   Error: Invalid correlation ID
   ```
   Solution: Ensure correlation ID is a non-empty string

### Debug Mode

Enable debug mode to see detailed logging information:
```javascript
process.env.LOG_LEVEL = 'debug';
```

## Requirements

- Node.js >= 12.0.0
- Winston >= 3.8.2

## Best Practices

1. Always set a meaningful correlation ID
2. Use appropriate log levels
3. Include relevant context in log messages
4. Set `isSenstiveData` flag for sensitive information
5. Keep component names consistent
6. Use appropriate statuses for audit logs

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## License

ISC License - see the [LICENSE](LICENSE) file for details

## Author

Amar Panigrahy

## Support

For support, please [open an issue](https://github.com/amar02041988/logging-audit-utils/issues) in the GitHub repository.