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

package/dist/uoaHttps.js

@@ -22,6 +22,15 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const https = __importStar(require("https"));
 const api_1 = require("@opentelemetry/api");
@@ -35,17 +44,175 @@ function request(...args) {
         return https.request(args[0], args[1]);
     }
 }
-function get(...args) {
-    if (args[2]) {
-        api_1.propagation.inject(api_1.context.active(), args[1].headers);
-        return https.get(args[0], args[1], args[2]);
-    }
-    else {
-        api_1.propagation.inject(api_1.context.active(), args[0].headers);
-        return https.get(args[0], args[1]);
-    }
+function doGetRequest(hostname, path, headers) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise(function (resolve, reject) {
+            const options = {
+                "method": "GET",
+                "hostname": hostname,
+                "path": path,
+                "headers": headers
+            };
+            api_1.propagation.inject(api_1.context.active(), options.headers);
+            const req = https.request(options, function (response) {
+                const chunks = [];
+                response.on("data", function (chunk) {
+                    chunks.push(chunk);
+                });
+                response.on("end", function () {
+                    let body = Buffer.concat(chunks);
+                    body = JSON.parse(body.toString());
+                    resolve(body);
+                });
+                response.on("error", function (e) {
+                    reject(e);
+                });
+            });
+            req.end();
+        });
+    });
+}
+function doPostRequest(hostname, path, headers, data) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise(function (resolve, reject) {
+            const options = {
+                "method": "POST",
+                "hostname": hostname,
+                "path": path,
+                "headers": headers
+            };
+            api_1.propagation.inject(api_1.context.active(), options.headers);
+            const req = https.request(options, function (response) {
+                const chunks = [];
+                response.on("data", function (chunk) {
+                    chunks.push(chunk);
+                });
+                response.on("end", function () {
+                    if (response.statusCode == 204) {
+                        //204 is no content, and most JSON parses blow up on an empty string
+                        resolve(null);
+                    }
+                    else {
+                        let body = Buffer.concat(chunks);
+                        if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                            body = JSON.parse(body.toString());
+                        }
+                        else {
+                            body = body.toString();
+                        }
+                        resolve(body);
+                    }
+                });
+                response.on("error", function (e) {
+                    reject(e);
+                });
+            });
+            if (data) {
+                if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                    //We serialize using JSON.stringify as a default, or if a JSON is specified
+                    req.write(JSON.stringify(data));
+                }
+                else {
+                    // If another content-type is specified however, we respect the serialization provided
+                    req.write(data);
+                }
+            }
+            req.end();
+        });
+    });
+}
+function doPutRequest(hostname, path, headers, data) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise(function (resolve, reject) {
+            const options = {
+                "method": "PUT",
+                "hostname": hostname,
+                "path": path,
+                "headers": headers
+            };
+            api_1.propagation.inject(api_1.context.active(), options.headers);
+            const req = https.request(options, function (response) {
+                const chunks = [];
+                response.on("data", function (chunk) {
+                    chunks.push(chunk);
+                });
+                response.on("end", function () {
+                    if (response.statusCode == 204) {
+                        //204 is no content, and most JSON parses blow up on an empty string
+                        resolve(null);
+                    }
+                    else {
+                        let body = Buffer.concat(chunks);
+                        if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                            body = JSON.parse(body.toString());
+                        }
+                        else {
+                            body = body.toString();
+                        }
+                        resolve(body);
+                    }
+                });
+                response.on("error", function (e) {
+                    reject(e);
+                });
+            });
+            if (data) {
+                if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                    //We serialize using JSON.stringify as a default, or if a JSON is specified
+                    req.write(JSON.stringify(data));
+                }
+                else {
+                    // If another content-type is specified however, we respect the serialization provided
+                    req.write(data);
+                }
+            }
+            req.end();
+        });
+    });
+}
+function doDeleteRequest(hostname, path, headers) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise(function (resolve, reject) {
+            const options = {
+                "method": "DELETE",
+                "hostname": hostname,
+                "path": path,
+                "headers": headers
+            };
+            api_1.propagation.inject(api_1.context.active(), options.headers);
+            const req = https.request(options, function (response) {
+                const chunks = [];
+                response.on("data", function (chunk) {
+                    chunks.push(chunk);
+                });
+                response.on("end", function () {
+                    if (response.statusCode == 204) {
+                        //204 is no content, and most JSON parses blow up on an empty string
+                        resolve(null);
+                    }
+                    else {
+                        let body = Buffer.concat(chunks);
+                        if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                            body = JSON.parse(body.toString());
+                        }
+                        else {
+                            body = body.toString();
+                        }
+                        resolve(body);
+                    }
+                });
+                response.on("error", function (e) {
+                    reject(e);
+                });
+            });
+            req.end();
+        });
+    });
 }
 module.exports = {
     request,
-    get
+    doGetRequest,
+    doPostRequest,
+    doPutRequest,
+    doDeleteRequest
 };

package/package.json

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

package/readme.md

@@ -1,4 +1,128 @@
 ![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');
+```
+
+The `uoaHttps` module exposes some functions to perform the primary HTTP operations. These will inject the tracing headers into requests before they are made:
+
+```
+doGetRequest(hostname, path, headers): Promise
+doPostRequest(hostname, path, headers, data): Promise
+doPutRequest(hostname, path, headers, data): Promise
+doDeleteRequest(hostname, path, headers): Promise
+```
+
+There is also another function `request()` exposed in this module in case header propagation with operations other than the basic GET, POST, PUT, and DELETE are required.\
+The usage of this is the same as the one provided by the Node https library (see 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.

package/uoaHttps.ts

@@ -16,19 +16,183 @@ function request(...args: any[]): http.ClientRequest {
     }
 }
 
-function get(options: RequestOptions | string | URL, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
-function get(url: string | URL, options: RequestOptions, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
-function get(...args: any[]): http.ClientRequest {
-    if (args[2]) {
-        propagation.inject(context.active(), args[1].headers);
-        return https.get(args[0], args[1], args[2]);
-    } else {
-        propagation.inject(context.active(), args[0].headers);
-        return https.get(args[0], args[1]);
-    }
+async function doGetRequest(hostname: string, path: string, headers: any) {
+    return new Promise(function (resolve, reject) {
+        const options = {
+            "method": "GET",
+            "hostname": hostname,
+            "path": path,
+            "headers": headers
+        }
+        propagation.inject(context.active(), options.headers);
+
+        const req = https.request(options, function (response) {
+            const chunks: any[] = [];
+
+            response.on("data", function (chunk) {
+                chunks.push(chunk);
+            });
+
+            response.on("end", function () {
+                let body = Buffer.concat(chunks);
+                body = JSON.parse(body.toString());
+                resolve(body);
+            });
+
+            response.on("error", function (e) {
+                reject(e);
+            })
+        });
+
+        req.end();
+    });
+}
+
+async function doPostRequest(hostname: string, path: string, headers: any, data: any) {
+    return new Promise(function (resolve, reject) {
+        const options = {
+            "method": "POST",
+            "hostname": hostname,
+            "path": path,
+            "headers": headers
+        }
+        propagation.inject(context.active(), options.headers);
+
+        const req = https.request(options, function (response) {
+            const chunks: any[] = [];
+
+            response.on("data", function (chunk) {
+                chunks.push(chunk);
+            });
+
+            response.on("end", function () {
+                if (response.statusCode == 204) {
+                    //204 is no content, and most JSON parses blow up on an empty string
+                    resolve(null);
+                } else {
+                    let body: any = Buffer.concat(chunks);
+                    if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                        body = JSON.parse(body.toString());
+                    } else {
+                        body = body.toString();
+                    }
+                    resolve(body);
+                }
+            });
+
+            response.on("error", function (e) {
+                reject(e);
+            })
+        });
+
+        if (data) {
+            if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                //We serialize using JSON.stringify as a default, or if a JSON is specified
+                req.write(JSON.stringify(data));
+            } else {
+                // If another content-type is specified however, we respect the serialization provided
+                req.write(data);
+            }
+        }
+        req.end();
+    });
+}
+
+async function doPutRequest(hostname: string, path: string, headers: any, data: any) {
+    return new Promise(function (resolve, reject) {
+        const options = {
+            "method": "PUT",
+            "hostname": hostname,
+            "path": path,
+            "headers": headers
+        }
+        propagation.inject(context.active(), options.headers);
+
+        const req = https.request(options, function (response) {
+            const chunks: any[] = [];
+
+            response.on("data", function (chunk) {
+                chunks.push(chunk);
+            });
+
+            response.on("end", function () {
+                if (response.statusCode == 204) {
+                    //204 is no content, and most JSON parses blow up on an empty string
+                    resolve(null);
+                } else {
+                    let body: any = Buffer.concat(chunks);
+                    if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                        body = JSON.parse(body.toString());
+                    } else {
+                        body = body.toString();
+                    }
+                    resolve(body);
+                }
+            });
+
+            response.on("error", function (e) {
+                reject(e);
+            })
+        });
+
+        if (data) {
+            if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                //We serialize using JSON.stringify as a default, or if a JSON is specified
+                req.write(JSON.stringify(data));
+            } else {
+                // If another content-type is specified however, we respect the serialization provided
+                req.write(data);
+            }
+        }
+        req.end();
+    });
+}
+
+async function doDeleteRequest(hostname: string, path: string, headers: any) {
+    return new Promise(function (resolve, reject) {
+        const options = {
+            "method": "DELETE",
+            "hostname": hostname,
+            "path": path,
+            "headers": headers
+        }
+        propagation.inject(context.active(), options.headers);
+
+        const req = https.request(options, function (response) {
+            const chunks: any[] = [];
+
+            response.on("data", function (chunk) {
+                chunks.push(chunk);
+            });
+
+            response.on("end", function () {
+                if (response.statusCode == 204) {
+                    //204 is no content, and most JSON parses blow up on an empty string
+                    resolve(null);
+                } else {
+                    let body: any = Buffer.concat(chunks);
+                    if (!('Content-Type' in options.headers) || options.headers['Content-Type'] === 'application/json') {
+                        body = JSON.parse(body.toString());
+                    } else {
+                        body = body.toString();
+                    }
+                    resolve(body);
+                }
+            });
+
+            response.on("error", function (e) {
+                reject(e);
+            })
+        });
+
+        req.end();
+    });
 }
 
 module.exports = {
     request,
-    get
+    doGetRequest,
+    doPostRequest,
+    doPutRequest,
+    doDeleteRequest
 }