sprinting-retail-common

Sprinting Retail Comon

Introduction

This library provides:

• Error handling
• Logging to ELK - both logs and APM

Check out the RELEASE_LETTERS here

Setup

1. Install in your project

$ npm i sprinting-retail-common

2. Add CommonAppModule to your AppModule using forRoot to pass config which must implement the RetailCommonConfig interface.

import { CommonAppModule } from "sprinting-retail-common"
...
const config: RetailCommonConfig = {
    ...assign config properties from your AppConfig...
}
...
@Module(
  {
    imports: [
      CommonAppModule.forRoot(config),
      ...
    ],
    ...
  }
)
export class AppModule {}

Using the LoggerService

Once you have imported CommonAppModule in your AppModule, the LoggerService with be provided globally.

This means you can inject the LoggerService in the constructor of your controllers or providers like here: With this you can log messages, events and errors as shown below.

export class DevSupportController {
    constructor(private readonly logger: LoggerService) { }

    @Get("trigger-logs") async triggerLogs()
    {
      const contextData = { a: 1, b: 2 }
      this.logger.info(__filename, "my message info", contextData)
      this.logger.debug(__filename, "my message info", contextData)
      this.logger.warn(__filename, "my message info", contextData)
      this.logger.logError(new Exception("SomeError", "Some description", contextData, innerError))
      this.logger.event(__fileName, "SomeEvent", { someKey: "someValue" }, "SomeCategory")
    }
}

Please notice:

• You have three normal log methods: info, debug and warn, each taking a message and contextData. ContextData will be serialized and concatenated to the message field in ELK.
• You have a special method logError for error handling. You have to create an AppException or one of the derived classes to invoke it.
• You have a special method event for logging custom events. You have to pass an eventName, eventData and eventCategory.

Using the error classes

You should preferably use the following error classes for error handling:

• Exception is a custom exception class which extends Error. You need to provide a http status for this exception.
• ServerException is a custom exception class which extends Exception, use it for internal server errors. It has http status 500.
• ClientException is a custom exception class which extends Exception, use it for errors that you assume to be caused by the clients calling your API. It has http status 400

We have these additional exception classes for special occasions:

• CustomBadRequestException
• SecurityException

If needed you can create your own exception classes by extending the AppException class - although it should not be necessary under normal circumstances.

The logError function will both log the error as part of application logs and at the same time send the error to APM

    this.logger.logError(new ForbiddenException('Access denied'), {});

Publishing a new version of this library

We publish new versions to npm from a developer machine. It is done like this:

• Make sure to update the RELEASE_LETTERS.md file
• Run npm run publish-prepare
• If any final changes were made in the previous step, commit these as well.
• Increment the version number in package.json
• Commit the increment with message "Release version x.y"
• Run npm run publish-complete

Appendix

For the sending logs the module using Logstash UDP transport. To test if udp port is responding, use netcat.

$ nc -v -u -z -w 3 10.0.0.xxx 5xxx