1.0.0 • Published 1 month ago

@smarterservices/smarter-logging v1.0.0

Weekly downloads
-
License
ISC
Repository
bitbucket
Last release
1 month ago

SmarterLogging

Build Status Test Coverage npm version License: ISC Node.js Version Private Package

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
1.0.0

1 month ago

0.0.3

5 years ago

0.0.2

5 years ago

0.0.1

5 years ago