@uoa/lambda-tracing 1.0.0-beta.0

package/UoaB3Propagator.ts

@@ -0,0 +1,156 @@
+/**
+ * Class extended from OpenTelemetry B3MultiPropagator so that we can propagate & log the X-B3-Info header
+ *
+ * See {@link https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-propagator-b3/src/B3MultiPropagator.ts}
+ */
+ import {
+  Context,
+  isSpanContextValid,
+  trace,
+  TextMapGetter,
+  TextMapPropagator,
+  TextMapSetter,
+  TraceFlags,
+  createContextKey
+} from '@opentelemetry/api';
+import { isTracingSuppressed } from '@opentelemetry/core';
+import {getRequestId} from "./tracing";
+
+
+export const X_B3_TRACE_ID = 'x-b3-traceid';
+export const X_B3_SPAN_ID = 'x-b3-spanid';
+export const X_B3_SAMPLED = 'x-b3-sampled';
+export const X_B3_PARENT_SPAN_ID = 'x-b3-parentspanid';
+export const X_B3_FLAGS = 'x-b3-flags';
+export const X_B3_INFO = 'x-b3-info';
+export const B3_DEBUG_FLAG_KEY = createContextKey(
+  'B3 Debug Flag'
+);
+export const B3_INFO_KEY = createContextKey(
+  'B3 Info Header'
+)
+
+const VALID_SAMPLED_VALUES = new Set([true, 'true', 'True', '1', 1]);
+const VALID_UNSAMPLED_VALUES = new Set([false, 'false', 'False', '0', 0]);
+
+function parseHeader(header: unknown) {
+  return Array.isArray(header) ? header[0] : header;
+}
+
+function getHeaderValue(carrier: unknown, getter: TextMapGetter, key: string) {
+  const header = getter.get(carrier, key);
+  return parseHeader(header);
+}
+
+function getTraceId(carrier: unknown, getter: TextMapGetter): string {
+  const traceId = getHeaderValue(carrier, getter, X_B3_TRACE_ID);
+  if (typeof traceId === 'string') {
+      return traceId.padStart(32, '0');
+  }
+  return '';
+}
+
+function getSpanId(carrier: unknown, getter: TextMapGetter): string {
+  const spanId = getHeaderValue(carrier, getter, X_B3_SPAN_ID);
+  if (typeof spanId === 'string') {
+      return spanId;
+  }
+  return 'aaaaaaaaaaaaaaaa'; //Valid dummy value as spanId will change when AwsLambdaInstrumentation is initialised
+}
+
+function getDebug(carrier: unknown, getter: TextMapGetter): string | undefined {
+  const debug = getHeaderValue(carrier, getter, X_B3_FLAGS);
+  return debug === '1' ? '1' : undefined;
+}
+
+function getTraceFlags(
+  carrier: unknown,
+  getter: TextMapGetter
+): TraceFlags | undefined {
+  const traceFlags = getHeaderValue(carrier, getter, X_B3_SAMPLED);
+  const debug = getDebug(carrier, getter);
+  if (debug === '1' || VALID_SAMPLED_VALUES.has(traceFlags)) {
+      return TraceFlags.SAMPLED;
+  }
+  if (traceFlags === undefined || VALID_UNSAMPLED_VALUES.has(traceFlags)) {
+      return TraceFlags.NONE;
+  }
+  // This indicates to isValidSampledValue that this is not valid
+  return;
+}
+
+function getInfo(carrier: unknown, getter: TextMapGetter): string {
+  const info = getHeaderValue(carrier, getter, X_B3_INFO);
+  if (typeof info === 'string') {
+      return info;
+  }
+  return undefined;
+}
+
+export class UoaB3Propagator implements TextMapPropagator {
+  inject(context: Context, carrier: any, setter: TextMapSetter<any>): void {
+      const spanContext = trace.getSpanContext(context);
+      if (
+          !spanContext ||
+          !isSpanContextValid(spanContext) ||
+          isTracingSuppressed(context)
+      )
+          return;
+
+      const debug = context.getValue(B3_DEBUG_FLAG_KEY);
+      setter.set(carrier, X_B3_TRACE_ID, spanContext.traceId);
+      setter.set(carrier, X_B3_SPAN_ID, spanContext.spanId);
+      const info = context.getValue(B3_INFO_KEY);
+      if (info) {
+          setter.set(carrier, X_B3_INFO, info.toString());
+      } else if (getRequestId()) {
+          setter.set(carrier, X_B3_INFO, `lambdaRequestId:${getRequestId()}`);
+      }
+      // According to the B3 spec, if the debug flag is set,
+      // the sampled flag shouldn't be propagated as well.
+      if (debug === '1') {
+          setter.set(carrier, X_B3_FLAGS, debug);
+      } else if (spanContext.traceFlags !== undefined) {
+          // We set the header only if there is an existing sampling decision.
+          // Otherwise we will omit it => Absent.
+          setter.set(
+              carrier,
+              X_B3_SAMPLED,
+              (TraceFlags.SAMPLED & spanContext.traceFlags) === TraceFlags.SAMPLED
+                  ? '1'
+                  : '0'
+          );
+      }
+  }
+
+  extract(context: Context, carrier: any, getter: TextMapGetter<any>): Context {
+      const traceId = getTraceId(carrier, getter);
+      const spanId = getSpanId(carrier, getter);
+      const traceFlags = getTraceFlags(carrier, getter) as TraceFlags;
+      const debug = getDebug(carrier, getter);
+      const info = getInfo(carrier, getter);
+
+      context = context.setValue(B3_DEBUG_FLAG_KEY, debug);
+      if (info) {
+          context = context.setValue(B3_INFO_KEY, info);
+      }
+      return trace.setSpanContext(context, {
+          traceId,
+          spanId,
+          isRemote: true,
+          traceFlags,
+      });
+  }
+
+  fields(): string[] {
+      return [
+          X_B3_TRACE_ID,
+          X_B3_SPAN_ID,
+          X_B3_FLAGS,
+          X_B3_SAMPLED,
+          X_B3_PARENT_SPAN_ID,
+          X_B3_INFO
+      ];
+  }
+
+}

package/logging.ts

@@ -0,0 +1,73 @@
+import {B3_INFO_KEY} from "./UoaB3Propagator";
+import {getRequestId} from "./tracing";
+
+const winston = require('winston');
+const moment = require('moment');
+const path = require('path');
+const {trace, context} = require('@opentelemetry/api');
+
+const defaultLogPattern = '%date [%thread] %level %class - [[[%traceId,%spanId,%info]]] %message'
+const uoaLogLevels = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3
+}
+
+const uoaLoggingFormat = function(callingModule: NodeModule) {
+    return winston.format.printf((logInfo: any) => {
+        let logPattern = process.env.loggingPattern ? process.env.loggingPattern : defaultLogPattern;
+
+        const logReplacements = getLogReplacementValues(callingModule, logInfo);
+        logReplacements.forEach((value, key) => {
+            logPattern = logPattern.replace(key, value);
+        });
+
+        return logPattern;
+    });
+}
+
+function getLogReplacementValues(callingModule: NodeModule, logInfo: any): Map<string, string> {
+    const parts = callingModule.filename.substring(0, callingModule.filename.lastIndexOf('.js')).split(path.sep);
+    const moduleParts = parts.slice(parts.indexOf('src'));
+
+    let traceId = '-';
+    let spanId = '-';
+    const currentContext = trace.getSpanContext(context.active());
+    if (currentContext) {
+        traceId = currentContext.traceId;
+        spanId = currentContext.spanId;
+    }
+
+    let info = '-';
+    const infoHeader = context.active().getValue(B3_INFO_KEY);
+    if (infoHeader) {
+        info = infoHeader.toString();
+    } else if (getRequestId()) {
+        info = `lambdaRequestId:${getRequestId()}`;
+    }
+
+    let logReplacements: Map<string, string> = new Map<string, string>();
+    logReplacements.set('%date', moment().toISOString());
+    logReplacements.set('%thread', '-');
+    logReplacements.set('%level', logInfo.level.toUpperCase());
+    logReplacements.set('%class', moduleParts.join('.'));
+    logReplacements.set('%traceId', traceId);
+    logReplacements.set('%spanId', spanId);
+    logReplacements.set('%info', info);
+    logReplacements.set('%message', logInfo.message);
+
+    return logReplacements;
+}
+
+module.exports = function (callingModule: NodeModule) {
+    return winston.createLogger({
+        levels: uoaLogLevels,
+        transports: [
+            new winston.transports.Console({
+                level: process.env.loggingLevel ? process.env.loggingLevel.toLowerCase() : 'info'
+            })
+        ],
+        format: uoaLoggingFormat(callingModule)
+    });
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@uoa/lambda-tracing",
+  "version": "1.0.0-beta.0",
+  "description": "Library for logging & distributed tracing in UoA Lambda projects",
+  "main": "tracing.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@bitbucket.org/uoa/lambda-tracing.git"
+  },
+  "author": "Mitchell Faulconbridge <mitchell.faulconbridge@auckland.ac.nz>",
+  "license": "MIT",
+  "homepage": "https://bitbucket.org/uoa/lambda-tracing#readme",
+  "keywords": [
+    "uoa",
+    "lambda",
+    "logging",
+    "distributed-tracing"
+  ],
+  "exports": {
+    ".": "./tracing.ts",
+    "./uoaHttps": "./uoaHttps.ts",
+    "./logging": "./logging.ts"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.1.0",
+    "@opentelemetry/core": "^1.2.0",
+    "@opentelemetry/instrumentation": "^0.28.0",
+    "@opentelemetry/instrumentation-aws-lambda": "^0.31.0",
+    "@opentelemetry/sdk-trace-node": "^1.2.0",
+    "moment": "^2.29.3",
+    "winston": "^3.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^17.0.35"
+  }
+}

package/readme.md

@@ -0,0 +1,4 @@
+![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 Auckland University AWS Lambda projects.

package/tracing.ts

@@ -0,0 +1,30 @@
+import {NodeTracerProvider} from '@opentelemetry/sdk-trace-node';
+import {AwsLambdaInstrumentation} from '@opentelemetry/instrumentation-aws-lambda';
+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 getRequestId() {
+    return requestId;
+}

package/uoaHttps.ts

@@ -0,0 +1,34 @@
+import * as https from "https";
+import * as http from "http";
+import { URL } from "url";
+import {context, propagation} from "@opentelemetry/api";
+import {RequestOptions} from "https";
+
+function request(options: RequestOptions | string | URL, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
+function request(url: string | URL, options: RequestOptions, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
+function request(...args: any[]): http.ClientRequest {
+    if (args[2]) {
+        propagation.inject(context.active(), args[1].headers);
+        return https.request(args[0], args[1], args[2]);
+    } else {
+        propagation.inject(context.active(), args[0].headers);
+        return https.request(args[0], args[1]);
+    }
+}
+
+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]);
+    }
+}
+
+module.exports = {
+    request,
+    get
+}