docs: example

example/helpers/maths.js

@@ -0,0 +1,19 @@
+const { logger } = require("../services/logger");
+const { delay } = require("../services/helper");
+
+const multiply = async (n, factor) => {
+    const sleepMs = Math.floor(Math.random() * 1000 * factor);
+
+    await delay(sleepMs);
+
+    const result = n * factor;
+
+    /**
+     * Log a single multiplication result with an additional userid value
+     */
+    logger.debug("Multiply", { n, duration: sleepMs, result, userid: "mySecretUser" });
+
+    return result;
+};
+
+module.exports = { multiply };

example/index.js

@@ -0,0 +1,3 @@
+const { main } = require("./multiply");
+
+main({ factor: 2 });

example/multiply.js

@@ -0,0 +1,76 @@
+const { logger, metricUnits } = require("./services/logger.js");
+const { multiply } = require("./helpers/maths.js");
+const MAX_FACTOR = 10;
+/**
+ *
+ * @typedef {Object} event
+ * @property {number} factor -- multiplication factor (optional)
+ * @property {string} correlationId -- An existing correlationId (optional)
+ * @param {*} context -- Lambda context
+ */
+const main = async (event, context) => {
+    try {
+        /**
+         * Set the correlation or create a new one
+         */
+        logger.setCorrelationId(event.correlationId);
+
+        /**
+         * Log event, context and environment variables
+         */
+        logger.logInputEvent({ event, context, env: process.env });
+
+        /**
+         * Set the handler name on all log outputs
+         */
+        logger.addContextKey({
+            handlerNamespace: "multiply",
+        });
+
+        /**
+         * Add the factor to all future log outputs
+         */
+        if (event.factor) {
+            logger.addContextKey({ factor: event.factor });
+            if (event.factor > MAX_FACTOR) {
+                const cause = { factor: event.factor, limit: 10, reason: "too big" };
+                /**
+                 * Log the error with a payload
+                 */
+                logger.error("invalid factor", cause);
+                throw new RangeError("invalid factor", { cause });
+            }
+        }
+
+        const start = new Date().getTime();
+        const promises = [1, 2, 3, 4, 5].map((n) => multiply(n, event.factor || 1));
+
+        const result = await Promise.all(promises);
+        const end = new Date().getTime();
+
+        /**
+         * Log with additional attribute to mask
+         */
+        logger.warn("result", { result }, {}, ["factor"]);
+
+        /**
+         * Create a metric for the duration per factor
+         */
+        logger.metric("multiply", {
+            name: "Duration",
+            unit: metricUnits.Milliseconds,
+            value: end - start,
+            dimensions: [["factor", (event.factor || "1").toString()]],
+        });
+    } catch (error) {
+        /**
+         * Log the error with an error object
+         */
+
+        logger.error("global error", error);
+    } finally {
+        logger.clearLogContext();
+    }
+};
+
+module.exports = { main };

example/services/helper.js

@@ -0,0 +1,5 @@
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { delay };

example/services/logger.js

@@ -0,0 +1,4 @@
+const { Logger } = require("../../lib/cjs/index");
+const logger = new Logger("myService", "myApp");
+const metricUnits = Logger.METRIC_UNITS;
+module.exports = { logger, metricUnits };