@smarterservices/smarter-logging v1.0.0
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:
label
(string, optional): A category for the log. If not provided, defaults to 'Generic'.message
(string, required): The main log message.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:
- Add appropriate tests in the
tests
directory - Update this documentation
- 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:
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)
Commit the version change:
git add package.json git commit -m "Bump version to x.y.z"
Create and push a new tag:
git tag vx.y.z git push origin master --tags
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