@openapi-typescript-infra/service 2.7.6 → 2.8.0

package/build/types.d.ts

@@ -5,11 +5,10 @@ import type pino from 'pino';
 import type { Request, Response } from 'express';
 import type { Application } from 'express-serve-static-core';
 import type { middleware } from 'express-openapi-validator';
-import type { Meter, MeterProvider } from '@opentelemetry/api';
+import type { Meter } from '@opentelemetry/api';
 import type { ConfigStore } from './config/types';
 export interface InternalLocals extends Record<string, unknown> {
     server?: Server;
-    meterProvider: MeterProvider;
     mainApp: ServiceExpress;
 }
 export type ServiceLogger = pino.BaseLogger & Pick<pino.Logger, 'isLevelEnabled'>;

package/config/config.json

@@ -24,9 +24,6 @@
   "server": {
     "port": 8000,
     "internalPort": 3000,
-    "hostname": "localhost",
-    "metrics": {
-      "enabled": true
-    }
+    "hostname": "localhost"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-typescript-infra/service",
-  "version": "2.7.6",
+  "version": "2.8.0",
   "description": "An opinionated framework for building configuration driven services - web, api, or  ob. Uses OpenAPI, pino logging, express, confit, Typescript and vitest.",
   "main": "build/index.js",
   "scripts": {
@@ -67,6 +67,7 @@
     "@opentelemetry/instrumentation": "^0.43.0",
     "@opentelemetry/instrumentation-dns": "^0.32.2",
     "@opentelemetry/instrumentation-express": "^0.33.1",
+    "@opentelemetry/instrumentation-fetch": "^0.43.0",
     "@opentelemetry/instrumentation-generic-pool": "^0.32.2",
     "@opentelemetry/instrumentation-graphql": "^0.35.1",
     "@opentelemetry/instrumentation-http": "^0.43.0",
@@ -96,24 +97,24 @@
   "devDependencies": {
     "@commitlint/cli": "^17.7.1",
     "@commitlint/config-conventional": "^17.7.0",
-    "@openapi-typescript-infra/coconfig": "^4.1.0",
+    "@openapi-typescript-infra/coconfig": "^4.2.1",
     "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^10.0.4",
+    "@semantic-release/commit-analyzer": "^11.0.0",
     "@semantic-release/exec": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/release-notes-generator": "^11.0.7",
+    "@semantic-release/release-notes-generator": "^12.0.0",
     "@types/cookie-parser": "^1.4.4",
-    "@types/eventsource": "1.1.11",
-    "@types/express": "^4.17.17",
+    "@types/eventsource": "1.1.12",
+    "@types/express": "^4.17.18",
     "@types/glob": "^8.1.0",
-    "@types/lodash": "^4.14.198",
-    "@types/minimist": "^1.2.2",
-    "@types/node": "^20.6.2",
-    "@types/supertest": "^2.0.12",
-    "@typescript-eslint/eslint-plugin": "^6.7.0",
-    "@typescript-eslint/parser": "^6.7.0",
+    "@types/lodash": "^4.14.199",
+    "@types/minimist": "^1.2.3",
+    "@types/node": "^20.7.0",
+    "@types/supertest": "^2.0.13",
+    "@typescript-eslint/eslint-plugin": "^6.7.3",
+    "@typescript-eslint/parser": "^6.7.3",
     "coconfig": "^0.13.3",
-    "eslint": "^8.49.0",
+    "eslint": "^8.50.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-import": "^2.28.1",
     "pino-pretty": "^10.2.0",
@@ -122,7 +123,10 @@
     "ts-node": "^10.9.1",
     "tsconfig-paths": "^4.2.0",
     "typescript": "^5.2.2",
-    "vitest": "^0.34.4"
+    "vitest": "^0.34.5"
+  },
+  "resolutions": {
+    "qs": "^6.11.0"
   },
   "packageManager": "yarn@3.2.3"
 }

package/src/config/schema.ts

@@ -60,7 +60,6 @@ export interface ConfigurationSchema extends Record<string, unknown> {
   server: {
     internalPort?: number;
     port?: number;
-    metrics: ConfigurationItemEnabled;
     // To enable HTTPS on the main service, set the key and cert to the
     // actual key material (not the path). Use shortstop file: handler.
     // Note that generally it's better to offload tls termination,

package/src/express-app/app.ts

@@ -6,11 +6,7 @@ import path from 'path';
 import express from 'express';
 import { pino } from 'pino';
 import cookieParser from 'cookie-parser';
-import { MeterProvider } from '@opentelemetry/sdk-metrics';
-import { Resource } from '@opentelemetry/resources';
-import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
 import { metrics } from '@opentelemetry/api';
-import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
 import { createTerminus } from '@godaddy/terminus';
 import type { RequestHandler, Response } from 'express';
 
@@ -29,70 +25,13 @@ import type {
   ServiceOptions,
   ServiceStartOptions,
 } from '../types';
-import { ConfigurationItemEnabled, ConfigurationSchema } from '../config/schema';
+import { ConfigurationSchema } from '../config/schema';
 import { getNodeEnv, isDev } from '../env';
+import { getGlobalPrometheusExporter } from '../telemetry/index';
 
 import { loadRoutes } from './route-loader';
 import { startInternalApp } from './internal-server';
 
-const METRICS_KEY = Symbol('PrometheusMetricsInfo');
-
-interface InternalMetricsInfo {
-  meterProvider: MeterProvider;
-  exporter?: PrometheusExporter;
-}
-
-interface AppWithMetrics {
-  [METRICS_KEY]?: InternalMetricsInfo;
-}
-
-async function enableMetrics<SLocals extends ServiceLocals = ServiceLocals>(
-  app: ServiceExpress<SLocals>,
-  name: string,
-) {
-  const meterProvider = new MeterProvider({
-    resource: new Resource({
-      [SemanticResourceAttributes.SERVICE_NAME]: name,
-    }),
-  });
-  metrics.setGlobalMeterProvider(meterProvider);
-  app.locals.meter = meterProvider.getMeter(name);
-
-  const metricsConfig = app.locals.config.get<ConfigurationItemEnabled>('server:metrics');
-  const value: InternalMetricsInfo = { meterProvider };
-  if (metricsConfig?.enabled) {
-    const finalConfig = {
-      ...metricsConfig,
-      preventServerStart: true,
-    };
-    // There is what I would consider a bug in OpenTelemetry metrics
-    // wherein adding metrics BEFORE the metricReader is added results
-    // in those metrics screaming into the void. So, we need to add
-    // this up front and then just tie it to the internal express
-    // app if and when "listen" is called.
-    const exporter = new PrometheusExporter(finalConfig);
-    meterProvider.addMetricReader(exporter);
-    value.exporter = exporter;
-  } else {
-    app.locals.logger.info('No metrics will be exported');
-  }
-  // Squirrel it away for later
-  Object.defineProperty(app.locals, METRICS_KEY, {
-    value,
-    enumerable: false,
-    configurable: true,
-  });
-}
-
-async function endMetrics<SLocals extends ServiceLocals = ServiceLocals>(
-  app: ServiceExpress<SLocals>,
-) {
-  const { internalApp, logger } = app.locals;
-  const meterProvider = internalApp?.locals.meterProvider as MeterProvider | undefined;
-  await meterProvider?.shutdown();
-  logger.info('Metrics shutdown');
-}
-
 function isSyncLogging() {
   if (process.env.LOG_SYNC) {
     return true;
@@ -169,13 +108,7 @@ export async function startApp<
     await serviceImpl.attach(app);
   }
 
-  try {
-    await enableMetrics(app, name);
-  } catch (error) {
-    logger.error(error, 'Could not enable metrics.');
-    throw error;
-  }
-
+  app.locals.meter = metrics.getMeterProvider().getMeter(name);
   if (config.get('trustProxy')) {
     app.set('trust proxy', config.get('trustProxy'));
   }
@@ -313,7 +246,6 @@ export async function shutdownApp(app: ServiceExpress) {
   const { logger } = app.locals;
   try {
     await app.locals.service.stop?.(app);
-    await endMetrics(app);
     logger.info('App shutdown complete');
   } catch (error) {
     logger.warn(error, 'Shutdown failed');
@@ -375,7 +307,6 @@ export async function listen<SLocals extends ServiceLocals = ServiceLocals>(
     onShutdown() {
       return Promise.resolve()
         .then(() => service.stop?.(app))
-        .then(() => endMetrics(app))
         .then(shutdownHandler || Promise.resolve)
         .then(() => logger.info('Graceful shutdown complete'))
         .catch((error) => logger.error(error, 'Error terminating tracing'))
@@ -401,9 +332,6 @@ export async function listen<SLocals extends ServiceLocals = ServiceLocals>(
     logger.error(error, 'Main service listener error');
   });
 
-  const metricInfo = (app.locals as AppWithMetrics)[METRICS_KEY] as InternalMetricsInfo;
-  delete (app.locals as AppWithMetrics)[METRICS_KEY];
-
   // TODO handle rejection/error?
   const listenPromise = new Promise<void>((accept) => {
     server.listen(port, () => {
@@ -412,21 +340,21 @@ export async function listen<SLocals extends ServiceLocals = ServiceLocals>(
 
       const serverConfig = locals.config.get('server') as ConfigurationSchema['server'];
       // Ok now start the internal port if we have one.
-      if (serverConfig?.internalPort) {
+      if (serverConfig?.internalPort || serverConfig?.internalPort === 0) {
         startInternalApp(app, serverConfig.internalPort)
           .then((internalApp) => {
             locals.internalApp = internalApp;
-            internalApp.locals.meterProvider = metricInfo.meterProvider;
             locals.logger.info(
               { port: serverConfig.internalPort },
               'Internal metadata server started',
             );
           })
           .then(() => {
-            if (metricInfo.exporter) {
+            const prometheusExporter = getGlobalPrometheusExporter();
+            if (prometheusExporter) {
               locals.internalApp.get(
                 '/metrics',
-                metricInfo.exporter.getMetricsRequestHandler.bind(metricInfo.exporter),
+                prometheusExporter.getMetricsRequestHandler.bind(prometheusExporter),
               );
               locals.logger.info('Metrics exporter started');
             } else {

package/src/telemetry/index.ts

@@ -1,6 +1,7 @@
 import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
 import * as opentelemetry from '@opentelemetry/sdk-node';
+import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
 
 import type {
   DelayLoadServiceStartOptions,
@@ -31,17 +32,47 @@ function getExporter() {
   return new DummySpanExporter();
 }
 
+let prometheusExporter: PrometheusExporter | undefined;
+let telemetrySdk: opentelemetry.NodeSDK | undefined;
+
+/**
+ * OpenTelemetry is not friendly to the idea of stopping
+ * and starting itself, it seems. So we can only keep a global
+ * instance of the infrastructure no matter how many times
+ * you start/stop your service (this is mostly only relevant for testing).
+ * In addition, since we have to load it right away before configuration
+ * is available, we can't use configuration to decide anything.
+ */
+export function startGlobalTelemetry(serviceName: string) {
+  if (!prometheusExporter) {
+    prometheusExporter = new PrometheusExporter({ preventServerStart: true });
+    telemetrySdk = new opentelemetry.NodeSDK({
+      serviceName,
+      autoDetectResources: true,
+      traceExporter: getExporter(),
+      metricReader: prometheusExporter,
+      instrumentations: [getAutoInstrumentations()],
+    });
+    telemetrySdk.start();
+  }
+}
+
+export function getGlobalPrometheusExporter() {
+  return prometheusExporter;
+}
+
+export async function shutdownGlobalTelemetry() {
+  await prometheusExporter?.shutdown();
+  await telemetrySdk?.shutdown();
+  telemetrySdk = undefined;
+  prometheusExporter = undefined;
+}
+
 export async function startWithTelemetry<
   SLocals extends ServiceLocals = ServiceLocals,
   RLocals extends RequestLocals = RequestLocals,
 >(options: DelayLoadServiceStartOptions) {
-  const sdk = new opentelemetry.NodeSDK({
-    serviceName: options.name,
-    autoDetectResources: true,
-    traceExporter: getExporter(),
-    instrumentations: [getAutoInstrumentations()],
-  });
-  await sdk.start();
+  startGlobalTelemetry(options.name);
 
   // eslint-disable-next-line import/no-unresolved, @typescript-eslint/no-var-requires
   const { startApp, listen } = require('../express-app/app.js') as {
@@ -60,7 +91,7 @@ export async function startWithTelemetry<
   app.locals.logger.info('OpenTelemetry enabled');
 
   const server = await listen(app, async () => {
-    await sdk.shutdown();
+    await shutdownGlobalTelemetry();
     app.locals.logger.info('OpenTelemetry shut down');
   });
   return { app, server };

package/src/types.ts

@@ -4,13 +4,12 @@ import type pino from 'pino';
 import type { Request, Response } from 'express';
 import type { Application } from 'express-serve-static-core';
 import type { middleware } from 'express-openapi-validator';
-import type { Meter, MeterProvider } from '@opentelemetry/api';
+import type { Meter } from '@opentelemetry/api';
 
 import type { ConfigStore } from './config/types';
 
 export interface InternalLocals extends Record<string, unknown> {
   server?: Server;
-  meterProvider: MeterProvider;
   mainApp: ServiceExpress;
 }