feat(opentelemetry): create otel instrumentation for typed-express-router

packages/express-wrapper/src/request.ts

@@ -97,9 +97,15 @@ const createNamedFunction = <F extends (...args: any) => void>(
 export const onDecodeError: OnDecodeErrorFn = (errs, _req, res) => {
   const validationErrors = PathReporter.failure(errs);
   const validationErrorMessage = validationErrors.join('\n');
-  res.writeHead(400, { 'Content-Type': 'application/json' });
-  res.write(JSON.stringify({ error: validationErrorMessage }));
-  res.end();
+  return {
+    response: validationErrorMessage,
+    statusCode: 400,
+    responseFn: () => {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.write(JSON.stringify({ error: validationErrorMessage }));
+      res.end();
+    },
+  };
 };
 
 export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => {

packages/typed-express-router/package.json

@@ -23,11 +23,22 @@
     "fp-ts": "^2.0.0",
     "io-ts": "2.1.3"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@api-ts/superagent-wrapper": "0.0.0-semantically-released",
     "@swc-node/register": "1.10.9",
     "c8": "10.1.3",
-    "typescript": "4.7.4"
+    "typescript": "4.7.4",
+    "@opentelemetry/sdk-trace-base": "1.30.1",
+    "@opentelemetry/sdk-trace-node": "1.30.1",
+    "@opentelemetry/api": "1.9.0"
   },
   "publishConfig": {
     "access": "public"

packages/typed-express-router/src/errors.ts

@@ -2,14 +2,19 @@ import express from 'express';
 import { Errors } from 'io-ts';
 import * as PathReporter from 'io-ts/lib/PathReporter';
 
+import { OnDecodeErrorFn } from './types';
+
 export function defaultOnDecodeError(
   errs: Errors,
   _req: express.Request,
   res: express.Response,
-) {
+): ReturnType<OnDecodeErrorFn> {
   const validationErrors = PathReporter.failure(errs);
   const validationErrorMessage = validationErrors.join('\n');
-  res.status(400).json({ error: validationErrorMessage }).end();
+  const responseFn = () => {
+    res.status(400).json({ error: validationErrorMessage }).end();
+  };
+  return { response: validationErrorMessage, statusCode: 400, responseFn };
 }
 
 export function defaultOnEncodeError(

packages/typed-express-router/src/index.ts

@@ -8,6 +8,15 @@ import * as E from 'fp-ts/Either';
 import { pipe } from 'fp-ts/pipeable';
 import { defaultOnDecodeError, defaultOnEncodeError } from './errors';
 import { apiTsPathToExpress } from './path';
+import {
+  ApiTsAttributes,
+  createDecodeSpan,
+  createSendEncodedSpan,
+  endSpan,
+  recordSpanDecodeError,
+  recordSpanEncodeError,
+  setSpanAttributes,
+} from './telemetry';
 import {
   AddRouteHandler,
   AddUncheckedRouteHandler,
@@ -20,6 +29,8 @@ import {
   WrappedRouterOptions,
 } from './types';
 
+import type { Span } from '@opentelemetry/api';
+
 export type {
   AfterEncodedResponseSentFn,
   OnDecodeErrorFn,
@@ -81,12 +92,14 @@ export function wrapRouter<Spec extends ApiSpec>(
   ): AddUncheckedRouteHandler<Spec, Method> {
     return (apiName, handlers, options) => {
       const route: HttpRoute | undefined = spec[apiName]?.[method];
+      let decodeSpan: Span | undefined;
       if (route === undefined) {
         // Should only happen with an explicit undefined property, which we can only prevent at the
         // type level with the `exactOptionalPropertyTypes` tsconfig option
         throw Error(`Method "${method}" at "${apiName}" must not be "undefined"'`);
       }
       const wrapReqAndRes: UncheckedRequestHandler = (req, res, next) => {
+        decodeSpan = createDecodeSpan({ apiName, httpRoute: route });
         // Intentionally passing explicit arguments here instead of decoding
         // req by itself because of issues that arise while using Node 16
         // See https://github.com/BitGo/api-ts/pull/394 for more information.
@@ -103,6 +116,10 @@ export function wrapRouter<Spec extends ApiSpec>(
           status: keyof (typeof route)['response'],
           payload: unknown,
         ) => {
+          const encodeSpan = createSendEncodedSpan({
+            apiName,
+            httpRoute: route,
+          });
           try {
             const codec = route.response[status];
             if (!codec) {
@@ -112,6 +129,9 @@ export function wrapRouter<Spec extends ApiSpec>(
               typeof status === 'number'
                 ? status
                 : KeyToHttpStatus[status as keyof KeyToHttpStatus];
+            setSpanAttributes(encodeSpan, {
+              [ApiTsAttributes.API_TS_STATUS_CODE]: statusCode,
+            });
             if (statusCode === undefined) {
               throw new Error(`unknown HTTP status code for key ${status}`);
             } else if (!codec.is(payload)) {
@@ -126,18 +146,38 @@ export function wrapRouter<Spec extends ApiSpec>(
               res as WrappedResponse,
             );
           } catch (err) {
+            recordSpanEncodeError(encodeSpan, err);
             (options?.onEncodeError ?? onEncodeError)(
               err,
               req as WrappedRequest,
               res as WrappedResponse,
             );
+          } finally {
+            endSpan(encodeSpan);
           }
         };
         next();
       };
 
+      const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, res, next) => {
+        pipe(
+          req.decoded,
+          E.getOrElseW((errs) => {
+            const { response, statusCode } = (options?.onDecodeError ?? onDecodeError)(
+              errs,
+              req,
+              res,
+            );
+            recordSpanDecodeError(decodeSpan, response, statusCode);
+          }),
+        );
+        endSpan(decodeSpan);
+        next();
+      };
+
       const middlewareChain = [
         wrapReqAndRes,
+        endDecodeSpanMiddleware,
         ...routerMiddleware,
         ...handlers,
       ] as express.RequestHandler[];
@@ -164,7 +204,12 @@ export function wrapRouter<Spec extends ApiSpec>(
           req.decoded,
           E.matchW(
             (errs) => {
-              (options?.onDecodeError ?? onDecodeError)(errs, req, res);
+              const { responseFn } = (options?.onDecodeError ?? onDecodeError)(
+                errs,
+                req,
+                res,
+              );
+              responseFn();
             },
             (value) => {
               req.decoded = value;

packages/typed-express-router/src/telemetry.ts

@@ -0,0 +1,192 @@
+/*
+ * @api-ts/typed-express-router
+ */
+
+// This module handles the optional dependency on @opentelemetry/api
+// It provides functionality for creating spans for decode and sendEncoded operations
+
+import type { Attributes, Span, Tracer } from '@opentelemetry/api';
+
+import type { Json, SpanMetadata } from './types';
+
+let otelApi: any;
+let tracer: Tracer | undefined;
+
+// Load @opentelemetry/api, if available.
+try {
+  otelApi = require('@opentelemetry/api');
+  if (otelApi) {
+    tracer = otelApi.trace.getTracer('typed-express-router');
+  }
+} catch (e) {
+  // Optional dependency not available, so tracing will be disabled.
+  tracer = undefined;
+}
+
+export const ApiTsAttributes = {
+  /**
+   * The Operation ID of the HTTP request
+   */
+  API_TS_OPERATION_ID: 'api_ts.operation_id',
+
+  /**
+   * The method of the HTTP request
+   */
+  API_TS_METHOD: 'api_ts.method',
+
+  /**
+   * The path of the HTTP request
+   */
+  API_TS_PATH: 'api_ts.path',
+
+  /**
+   * Returned HTTP request status code
+   */
+  API_TS_STATUS_CODE: 'api_ts.status_code',
+};
+
+/**
+ * Create default attributes for decode spans
+ *
+ * @param metadata The metadata for a span
+ * @returns Record of span attributes
+ */
+export function createDefaultDecodeAttributes(metadata: SpanMetadata): Attributes {
+  const attributes: Attributes = {};
+
+  if (metadata.apiName) {
+    attributes[ApiTsAttributes.API_TS_OPERATION_ID] = metadata.apiName;
+  }
+
+  if (metadata.httpRoute) {
+    if (metadata.httpRoute.method) {
+      attributes[ApiTsAttributes.API_TS_METHOD] = metadata.httpRoute.method;
+    }
+    if (metadata.httpRoute.path) {
+      attributes[ApiTsAttributes.API_TS_PATH] = metadata.httpRoute.path;
+    }
+  }
+
+  return attributes;
+}
+
+/**
+ * Create default attributes for encode spans
+ *
+ * @param metadata The metadata for a span
+ * @returns Record of span attributes
+ */
+export function createDefaultEncodeAttributes(metadata: SpanMetadata): Attributes {
+  const attributes: Attributes = {};
+
+  if (metadata.apiName) {
+    attributes[ApiTsAttributes.API_TS_OPERATION_ID] = metadata.apiName;
+  }
+
+  if (metadata.httpRoute) {
+    if (metadata.httpRoute.method) {
+      attributes[ApiTsAttributes.API_TS_METHOD] = metadata.httpRoute.method;
+    }
+    if (metadata.httpRoute.path) {
+      attributes[ApiTsAttributes.API_TS_PATH] = metadata.httpRoute.path;
+    }
+  }
+
+  return attributes;
+}
+
+/**
+ * Creates a span for the decode operation if OpenTelemetry is available
+ * @param metadata The metadata for a span
+ * @returns A span object or undefined if tracing is disabled
+ */
+export function createDecodeSpan(metadata: SpanMetadata): Span | undefined {
+  if (!tracer || !otelApi) {
+    return undefined;
+  }
+
+  const span = tracer.startSpan(`typed-express-router.decode`);
+  const decodeAttributes = createDefaultDecodeAttributes(metadata);
+  span.setAttributes(decodeAttributes);
+
+  return span;
+}
+
+/**
+ * Creates a span for the sendEncoded operation if OpenTelemetry is available
+ * @param metadata The metadata for a span
+ * @returns A span object or undefined if tracing is disabled
+ */
+export function createSendEncodedSpan(metadata: SpanMetadata): Span | undefined {
+  if (!tracer || !otelApi) {
+    return undefined;
+  }
+
+  const span = tracer.startSpan(`typed-express-router.encode`);
+
+  const encodeAttributes = createDefaultEncodeAttributes(metadata);
+  // Add attributes to provide context for the span
+  span.setAttributes(encodeAttributes);
+
+  return span;
+}
+
+/**
+ * Records an error on an encode span
+ * @param span The span to record the error on
+ * @param error The error to record
+ */
+export function recordSpanEncodeError(span: Span | undefined, error: unknown): void {
+  if (!span || !otelApi) {
+    return;
+  }
+  span.recordException(error instanceof Error ? error : new Error(String(error)));
+  span.setStatus({ code: otelApi.SpanStatusCode.ERROR });
+}
+
+/**
+ * Records errors on a decode span
+ * @param span The span to record the errors on
+ * @param error The JSON error value to record
+ * @param statusCode The HTTP status code
+ */
+export function recordSpanDecodeError(
+  span: Span | undefined,
+  error: Json,
+  statusCode: number,
+): void {
+  if (!span || !otelApi) {
+    return;
+  }
+  setSpanAttributes(span, {
+    [ApiTsAttributes.API_TS_STATUS_CODE]: statusCode,
+  });
+  span.recordException(JSON.stringify(error, null, 2));
+  span.setStatus({ code: otelApi.SpanStatusCode.ERROR });
+}
+
+/**
+ * Sets a span's attributes if it exists
+ * @param span The span to modify
+ * @param attributes The attributes to modify the span with
+ */
+export function setSpanAttributes(
+  span: Span | undefined,
+  attributes: Attributes,
+): void {
+  if (!span) {
+    return;
+  }
+  span.setAttributes(attributes);
+}
+
+/**
+ * Ends a span if it exists
+ * @param span The span to end
+ */
+export function endSpan(span: Span | undefined): void {
+  if (!span) {
+    return;
+  }
+  span.end();
+}