SmarterLogging

Unified logging package for back end services that sends logs to BetterStack. This library provides a consistent logging interface across all services with support for different log levels, custom labels, and structured logging.

Installation

npm install @smarterservices/smarter-logging --save

Configuration

The library requires BetterStack credentials to be set as environment variables:

BETTERSTACK_SOURCE_TOKEN=your_source_token
BETTERSTACK_HOST=your_betterstack_host

Usage

Initialization

Before using any logging methods, you must initialize the logger with your application name:

const logging = require('@smarterservices/smarter-logging');

// Initialize with application name
logging.init('MyServiceName');

// Optionally add custom labels
logging.init('MyServiceName', {
  API: 'API',
  AUTH: 'Authentication',
  DB: 'Database'
});

Basic Logging

The library provides four logging levels:

// Error logging
logging.error('AUTH', 'Failed to authenticate user', errorObject);

// Info logging
logging.info('API', 'Request processed successfully', { requestId: '123', duration: 45 });

// Warning logging
logging.warn('DB', 'Database connection slow', { latency: 500 });

// Debug logging (only works in stage environment)
logging.debug('API', 'Processing request', { payload: req.body });

Parameters

All logging methods accept the same parameters:

1. label (string, optional): A category for the log. If not provided, defaults to 'Generic'.
2. message (string, required): The main log message.
3. object (any, optional): Additional data to include with the log. Can be an error object or any JSON-serializable data.

Custom Labels

You can define custom labels during initialization and use them throughout your application:

logging.init('MyServiceName', {
  AUTH: 'Authentication',
  PAYMENT: 'Payment Processing',
  USER: 'User Management'
});

// Later in your code
logging.info('AUTH', 'User logged in successfully');
logging.error('PAYMENT', 'Payment failed', errorObject);

Environment-specific Behavior

• Debug logs are only sent in the stage environment to prevent cluttering production logs.
• All logs include the current environment ([production], [stage], etc.) in the message.

Error Handling

The library handles errors internally:

• If the logger is not initialized, it logs an error to the console.
• If BetterStack credentials are missing, it logs an error during initialization.
• If sending a log to BetterStack fails, it logs the error to the console without throwing exceptions.

Testing

To run the tests:

npm test

For test coverage:

npm run test:coverage

Development

Adding New Features

When adding new features, make sure to:

1. Add appropriate tests in the tests directory
2. Update this documentation
3. Follow the existing code style

Running Linting

npm run lint

Code Coverage

This library maintains high test coverage (>94%) to ensure reliability. The coverage badge at the top of this README reflects the current branch coverage. You can generate a detailed coverage report by running:

npm run test:coverage

This will create a coverage report in the coverage directory that you can view in your browser.

Releasing and Versioning

This package follows semantic versioning (SemVer). To release a new version:

1. Update the version in package.json according to SemVer rules:

   • MAJOR version for incompatible API changes (x.0.0)
   • MINOR version for added functionality in a backward compatible manner (0.x.0)
   • PATCH version for backward compatible bug fixes (0.0.x)

2. Commit the version change:

   git add package.json
   git commit -m "Bump version to x.y.z"

3. Create and push a new tag:

   git tag vx.y.z
   git push origin master --tags

4. The Bitbucket Pipeline will automatically:

   • Run tests to verify the build
   • Publish the new version to the private NPM registry

Note: This package is published as a private NPM package, accessible only to authorized users within the organization.

Badges

The badges at the top of this README provide at-a-glance information about:

• Build Status: Shows if the latest build on the master branch is passing
• Test Coverage: Current branch test coverage percentage
• NPM Version: The latest version published to NPM
• License: The license under which this package is distributed
• Node.js Version: Shows the minimum required Node.js version (18+)
• Private Package: Indicates this is a private NPM package