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

packages/express-wrapper/src/index.ts

@@ -6,9 +6,22 @@
 import express from 'express';
 
 import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http';
-import { createRouter } from '@api-ts/typed-express-router';
+import {
+  createRouter,
+  DecodeErrorFormatterFn,
+  EncodeErrorFormatterFn,
+  GetDecodeErrorStatusCodeFn,
+  GetEncodeErrorStatusCodeFn,
+} from '@api-ts/typed-express-router';
 
-import { handleRequest, onDecodeError, onEncodeError, RouteHandler } from './request';
+import {
+  handleRequest,
+  defaultDecodeErrorFormatter,
+  defaultEncodeErrorFormatter,
+  defaultGetDecodeErrorStatusCode,
+  defaultGetEncodeErrorStatusCode,
+  RouteHandler,
+} from './request';
 import { defaultResponseEncoder, ResponseEncoder } from './response';
 
 export { middlewareFn, MiddlewareChain, MiddlewareChainOutput } from './middleware';
@@ -25,16 +38,26 @@ type CreateRouterProps<Spec extends ApiSpec> = {
     };
   };
   encoder?: ResponseEncoder;
+  decodeErrorFormatter?: DecodeErrorFormatterFn;
+  encodeErrorFormatter?: EncodeErrorFormatterFn;
+  getDecodeErrorStatusCode?: GetDecodeErrorStatusCodeFn;
+  getEncodeErrorStatusCode?: GetEncodeErrorStatusCodeFn;
 };
 
 export function routerForApiSpec<Spec extends ApiSpec>({
   spec,
   routeHandlers,
   encoder = defaultResponseEncoder,
+  decodeErrorFormatter = defaultDecodeErrorFormatter,
+  encodeErrorFormatter = defaultEncodeErrorFormatter,
+  getDecodeErrorStatusCode = defaultGetDecodeErrorStatusCode,
+  getEncodeErrorStatusCode = defaultGetEncodeErrorStatusCode,
 }: CreateRouterProps<Spec>) {
   const router = createRouter(spec, {
-    onDecodeError,
-    onEncodeError,
+    decodeErrorFormatter,
+    encodeErrorFormatter,
+    getDecodeErrorStatusCode,
+    getEncodeErrorStatusCode,
   });
   for (const apiName of Object.keys(spec)) {
     const resource = spec[apiName] as Spec[string];

packages/express-wrapper/src/request.ts

@@ -8,8 +8,10 @@ import * as PathReporter from 'io-ts/lib/PathReporter';
 
 import { ApiSpec, HttpRoute, RequestType, ResponseType } from '@api-ts/io-ts-http';
 import {
-  OnDecodeErrorFn,
-  OnEncodeErrorFn,
+  type DecodeErrorFormatterFn,
+  type EncodeErrorFormatterFn,
+  type GetDecodeErrorStatusCodeFn,
+  type GetEncodeErrorStatusCodeFn,
   TypedRequestHandler,
 } from '@api-ts/typed-express-router';
 
@@ -94,17 +96,28 @@ const createNamedFunction = <F extends (...args: any) => void>(
   fn: F,
 ): F => Object.defineProperty(fn, 'name', { value: name });
 
-export const onDecodeError: OnDecodeErrorFn = (errs, _req, res) => {
+export const defaultDecodeErrorFormatter: DecodeErrorFormatterFn = (errs, _req) => {
   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 { error: validationErrors.join('\n') };
 };
 
-export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => {
+export const defaultEncodeErrorFormatter: EncodeErrorFormatterFn = (_err, _req) => {
+  return {};
+};
+
+export const defaultGetDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = (
+  _errs,
+  _req,
+) => {
+  return 400;
+};
+
+export const defaultGetEncodeErrorStatusCode: GetEncodeErrorStatusCodeFn = (
+  err,
+  _req,
+) => {
   console.warn('Error in route handler:', err);
-  res.status(500).end();
+  return 500;
 };
 
 export const handleRequest = (

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

@@ -1,22 +1,22 @@
-import express from 'express';
-import { Errors } from 'io-ts';
 import * as PathReporter from 'io-ts/lib/PathReporter';
 
-export function defaultOnDecodeError(
-  errs: Errors,
-  _req: express.Request,
-  res: express.Response,
-) {
-  const validationErrors = PathReporter.failure(errs);
-  const validationErrorMessage = validationErrors.join('\n');
-  res.status(400).json({ error: validationErrorMessage }).end();
-}
+import type {
+  DecodeErrorFormatterFn,
+  EncodeErrorFormatterFn,
+  GetDecodeErrorStatusCodeFn,
+  GetEncodeErrorStatusCodeFn,
+} from './types';
 
-export function defaultOnEncodeError(
-  err: unknown,
-  _req: express.Request,
-  res: express.Response,
-) {
-  res.status(500).end();
-  console.warn(`Error in route handler: ${err}`);
-}
+export const defaultDecodeErrorFormatter: DecodeErrorFormatterFn = PathReporter.failure;
+
+export const defaultGetDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = (
+  _err,
+  _req,
+) => 400;
+
+export const defaultEncodeErrorFormatter: EncodeErrorFormatterFn = () => ({});
+
+export const defaultGetEncodeErrorStatusCode: GetEncodeErrorStatusCodeFn = (
+  _err,
+  _req,
+) => 500;

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

@@ -3,11 +3,27 @@
  */
 
 import { ApiSpec, HttpRoute, KeyToHttpStatus } from '@api-ts/io-ts-http';
+import type { Span } from '@opentelemetry/api';
 import express from 'express';
 import * as E from 'fp-ts/Either';
 import { pipe } from 'fp-ts/pipeable';
-import { defaultOnDecodeError, defaultOnEncodeError } from './errors';
+
+import {
+  defaultDecodeErrorFormatter,
+  defaultEncodeErrorFormatter,
+  defaultGetDecodeErrorStatusCode,
+  defaultGetEncodeErrorStatusCode,
+} from './errors';
 import { apiTsPathToExpress } from './path';
+import {
+  ApiTsAttributes,
+  createDecodeSpan,
+  createSendEncodedSpan,
+  endSpan,
+  recordSpanDecodeError,
+  recordSpanEncodeError,
+  setSpanAttributes,
+} from './telemetry';
 import {
   AddRouteHandler,
   AddUncheckedRouteHandler,
@@ -22,8 +38,10 @@ import {
 
 export type {
   AfterEncodedResponseSentFn,
-  OnDecodeErrorFn,
-  OnEncodeErrorFn,
+  DecodeErrorFormatterFn,
+  EncodeErrorFormatterFn,
+  GetDecodeErrorStatusCodeFn,
+  GetEncodeErrorStatusCodeFn,
   TypedRequestHandler,
   UncheckedRequestHandler,
   WrappedRouter,
@@ -43,17 +61,21 @@ export type {
 export function createRouter<Spec extends ApiSpec>(
   spec: Spec,
   {
-    onDecodeError,
-    onEncodeError,
+    encodeErrorFormatter,
+    getEncodeErrorStatusCode,
     afterEncodedResponseSent,
+    decodeErrorFormatter,
+    getDecodeErrorStatusCode,
     ...options
   }: WrappedRouterOptions = {},
 ): WrappedRouter<Spec> {
   const router = express.Router(options);
   return wrapRouter(router, spec, {
-    onDecodeError,
-    onEncodeError,
+    encodeErrorFormatter,
+    getEncodeErrorStatusCode,
     afterEncodedResponseSent,
+    decodeErrorFormatter,
+    getDecodeErrorStatusCode,
   });
 }
 
@@ -69,9 +91,11 @@ export function wrapRouter<Spec extends ApiSpec>(
   router: express.Router,
   spec: Spec,
   {
-    onDecodeError = defaultOnDecodeError,
-    onEncodeError = defaultOnEncodeError,
+    encodeErrorFormatter = defaultEncodeErrorFormatter,
+    getEncodeErrorStatusCode = defaultGetEncodeErrorStatusCode,
     afterEncodedResponseSent = () => {},
+    decodeErrorFormatter = defaultDecodeErrorFormatter,
+    getDecodeErrorStatusCode = defaultGetDecodeErrorStatusCode,
   }: WrappedRouteOptions,
 ): WrappedRouter<Spec> {
   const routerMiddleware: UncheckedRequestHandler[] = [];
@@ -81,12 +105,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 +129,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 +142,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 +159,42 @@ export function wrapRouter<Spec extends ApiSpec>(
               res as WrappedResponse,
             );
           } catch (err) {
-            (options?.onEncodeError ?? onEncodeError)(
-              err,
-              req as WrappedRequest,
-              res as WrappedResponse,
-            );
+            const statusCode = (
+              options?.getEncodeErrorStatusCode ?? getEncodeErrorStatusCode
+            )(err, req);
+            const encodeErrorMessage = (
+              options?.encodeErrorFormatter ?? encodeErrorFormatter
+            )(err, req);
+
+            recordSpanEncodeError(encodeSpan, err, statusCode);
+            res.status(statusCode).json(encodeErrorMessage);
+          } finally {
+            endSpan(encodeSpan);
           }
         };
         next();
       };
 
+      const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, _res, next) => {
+        pipe(
+          req.decoded,
+          E.getOrElseW((errs) => {
+            const decodeErrorMessage = (
+              options?.decodeErrorFormatter ?? decodeErrorFormatter
+            )(errs, req);
+            const statusCode = (
+              options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode
+            )(errs, req);
+            recordSpanDecodeError(decodeSpan, decodeErrorMessage, statusCode);
+          }),
+        );
+        endSpan(decodeSpan);
+        next();
+      };
+
       const middlewareChain = [
         wrapReqAndRes,
+        endDecodeSpanMiddleware,
         ...routerMiddleware,
         ...handlers,
       ] as express.RequestHandler[];
@@ -164,7 +221,13 @@ export function wrapRouter<Spec extends ApiSpec>(
           req.decoded,
           E.matchW(
             (errs) => {
-              (options?.onDecodeError ?? onDecodeError)(errs, req, res);
+              const statusCode = (
+                options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode
+              )(errs, req);
+              const decodeErrorMessage = (
+                options?.decodeErrorFormatter ?? decodeErrorFormatter
+              )(errs, req);
+              res.status(statusCode).json(decodeErrorMessage);
             },
             (value) => {
               req.decoded = value;