@uoa/lambda-tracing 1.0.0-beta.3 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uoa/lambda-tracing",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0",
   "description": "Library for logging & distributed tracing in UoA Lambda projects",
   "repository": {
     "type": "git",

package/readme.md

@@ -1,4 +1,116 @@
 ![npm (scoped)](https://img.shields.io/npm/v/@uoa/lambda-tracing)
 # UOA Lambda Tracing Library
+This library contains functions to enable distributed tracing & logging in University of Auckland AWS Lambda projects.
+
+## Usage
+### Installation
+Install the library using the command
+```
+npm install @uoa/lambda-tracing
+```
+
+### Setup
+In your src folder, create a new file `tracing-wrapper.ts`\
+In this, add the following code
+```
+import {initializeTracing} from "@uoa/lambda-tracing";
+
+initializeTracing();
+```
+
+In your lambda environment.yml file, add the following `NODE_OPTIONS` environment variable in the properties map
+```
+lambda:
+  properties:
+    NODE_OPTIONS: --require src/tracing-wrapper
+```
+
+The above ensures that the `tracing-wrapper.ts` code will be loaded before your lambda app starts, which will
+perform the required setup for logging and distributed tracing.
+
+### Logging
+Whenever you want to use the logging provided in this library, simply import the logger using
+```
+const logger = require('@uoa/lambda-tracing/logging')(module);
+```
+Note: `(module)` must be passed as a parameter to this import so that the logger knows where it has been called from.
+
+Once the logger has been imported, you can log any info using
+```
+logger.info('Hello Logger!');
+```
+
+####Logging Levels
+At UoA, we have four logging levels available to use. Ordered by decreasing priority, these are:
+
+|Level|    Logger usage    |
+|-----|--------------------|
+|ERROR|```logger.error()```|
+|WARN |```logger.warn()``` |
+|INFO |```logger.info()``` |
+|DEBUG|```logger.debug()```|
+
+By default, any log at the `INFO` level or higher will be logged. However, this can be changed by adding another
+environment variable `loggingLevel` in the lambda properties map of the environment.yml file. The value of this
+specifies the lowest level that will be logged.
+```
+lambda:
+  properties:
+    NODE_OPTIONS: --require src/tracing-wrapper
+    loggingLevel: WARN
+```
+```
+logger.debug('Will not be logged');
+logger.info('Will not be logged');
+logger.warn('Will be logged');
+logger.error('Will be logged');
+```
+
+####Logging format
+By default, logs will be produced in the following format:
+```
+date [thread] level class - [[[traceId,spanId,info]]] message
+```
+
+This can also be changed by adding another environment variable `loggingPattern` in the lambda properties map
+of the environment.yml file.
+```
+lambda:
+  properties:
+    NODE_OPTIONS: --require src/tracing-wrapper
+    loggingPattern: "%date - %message | %level | %class"
+```
+Valid logging pattern placeholders are as follows:
+
+|Placeholder|Replacement value|Example value|
+|-----------|-----------------|-----|
+|%date|Date time when the message is logged in ISO8601 format|2022-05-29T21:31:11.250Z|
+|%thread|Unused, this is only present in the default pattern to match with UoA logging standards. Value will always be ```-```|-|
+|%level|Log level|INFO|
+|%class|The module which logged the message|src.handle-service|
+|%traceId|Unique Id for the request|5c0c783c965a684842608f10422fdf2c|
+|%spanId|Unique Id for the current lambda invocation|6a8b025511ac1191|
+|%info|Extra information to help with filtering the logs|lambdaRequestId:dc2f1b60-96af-4869-9b75-036f9ddcdb33|
+|%message|The logged message|Hello Logger!|
+
+### Distributed Tracing
+There are two headers that can be passed in API calls to your lambda project using this library: ```X-B3-TraceId``` and ```X-B3-Info```.
+If passed to a lambda project using this library, the values of %traceId and %info in the logging pattern will be the corresponding header values. 
+
+`X-B3-TraceId` should be a 32 character lowercase hex encoded string.\
+If the passed traceId is less than 32
+characters, it will be left padded with 0's to get to a length of 32.\
+If this header is not passed, it will be randomly generated.
+
+`X-B3-Info` can be any string value to provide extra information in your logs.\
+If this header is not passed, it will be set as `lambdaRequestId:requestId` where `requestId` is the id of the current lambda invocation.
+
+####Header Propagation
+To propagate the ```X-B3-TraceId``` and ```X-B3-Info``` headers to other APIs, you can import and use the uoaHttps module:
+```
+const uoaHttps = require('@uoa/lambda-tracing/uoaHttps');
+```
+
+There are two functions exposed in this module: `get()` and `request()` which will inject the additional tracing headers into the request before it is made.\
+The usage of these is the same as the functions provided by the Node https library (see `get()` specs [here](https://nodejs.org/api/https.html#httpsgetoptions-callback) and `request()` specs [here](https://nodejs.org/api/https.html#httpsrequestoptions-callback)).
 
-This library contains functions to enable distributed tracing & logging in Auckland University AWS Lambda projects.