@uoa/lambda-tracing 1.0.0-beta.2 → 1.0.1

package/dist/tracing.d.ts

@@ -1 +1,2 @@
+export declare function initializeTracing(): void;
 export declare function getRequestId(): string;

package/dist/tracing.js

@@ -1,32 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRequestId = void 0;
+exports.getRequestId = exports.initializeTracing = void 0;
 const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
 const instrumentation_aws_lambda_1 = require("@opentelemetry/instrumentation-aws-lambda");
 const instrumentation_1 = require("@opentelemetry/instrumentation");
 const UoaB3Propagator_1 = require("./UoaB3Propagator");
 const provider = new sdk_trace_node_1.NodeTracerProvider();
-provider.register({
-    propagator: new UoaB3Propagator_1.UoaB3Propagator()
-});
 let requestId;
-(0, instrumentation_1.registerInstrumentations)({
-    instrumentations: [
-        new instrumentation_aws_lambda_1.AwsLambdaInstrumentation({
-            requestHook: (span, { event, context }) => {
-                span.setAttribute('faas.name', context.functionName);
-                requestId = context.awsRequestId;
-            },
-            responseHook: (span, { err, res }) => {
-                if (err instanceof Error)
-                    span.setAttribute('faas.error', err.message);
-                if (res)
-                    span.setAttribute('faas.res', res);
-            },
-            disableAwsContextPropagation: true
-        })
-    ],
-});
+function initializeTracing() {
+    provider.register({
+        propagator: new UoaB3Propagator_1.UoaB3Propagator()
+    });
+    (0, instrumentation_1.registerInstrumentations)({
+        instrumentations: [
+            new instrumentation_aws_lambda_1.AwsLambdaInstrumentation({
+                requestHook: (span, { event, context }) => {
+                    span.setAttribute('faas.name', context.functionName);
+                    requestId = context.awsRequestId;
+                },
+                responseHook: (span, { err, res }) => {
+                    if (err instanceof Error)
+                        span.setAttribute('faas.error', err.message);
+                    if (res)
+                        span.setAttribute('faas.res', res);
+                },
+                disableAwsContextPropagation: true
+            })
+        ]
+    });
+}
+exports.initializeTracing = initializeTracing;
 function getRequestId() {
     return requestId;
 }

package/package.json

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

package/readme.md

@@ -1,4 +1,119 @@
 ![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.

package/tracing.ts

@@ -4,26 +4,30 @@ import {registerInstrumentations} from '@opentelemetry/instrumentation';
 import {UoaB3Propagator} from "./UoaB3Propagator";
 
 const provider = new NodeTracerProvider();
-provider.register({
-    propagator: new UoaB3Propagator()
-});
 let requestId: string;
 
-registerInstrumentations({
-    instrumentations: [
-        new AwsLambdaInstrumentation({
-            requestHook: (span, { event, context }) => {
-                span.setAttribute('faas.name', context.functionName);
-                requestId = context.awsRequestId;
-            },
-            responseHook: (span, { err, res }) => {
-                if (err instanceof Error) span.setAttribute('faas.error', err.message);
-                if (res) span.setAttribute('faas.res', res);
-            },
-            disableAwsContextPropagation: true
-        })
-    ],
-});
+export function initializeTracing() {
+    provider.register({
+        propagator: new UoaB3Propagator()
+    });
+
+    registerInstrumentations({
+        instrumentations: [
+            new AwsLambdaInstrumentation({
+                requestHook: (span, { event, context }) => {
+                    span.setAttribute('faas.name', context.functionName);
+                    requestId = context.awsRequestId;
+                },
+                responseHook: (span, { err, res }) => {
+                    if (err instanceof Error) span.setAttribute('faas.error', err.message);
+                    if (res) span.setAttribute('faas.res', res);
+                },
+                disableAwsContextPropagation: true
+            })
+        ]
+    })
+
+}
 
 export function getRequestId() {
     return requestId;