API Telemetry and Monitoring for Node.js

Common errors

• Error: Cannot find module 'prom-client'

  cause `prom-client` is a peer dependency and must be installed explicitly in your project, but it is missing.
  fix Run `npm install prom-client` or `yarn add prom-client` in your project directory.

• API Responses page in built-in Telemetry UI is not responding (or slow) with ~1000 endpoints

  cause The built-in UI experienced performance issues when displaying a very large number of API endpoints.
  fix This issue was specifically addressed in `v0.99.2`. Upgrade `swagger-stats` to `0.99.2` or later to leverage performance improvements for the UI.

• body response show duplicate data (in Elasticsearch)

  cause Prior versions might have stored body responses inefficiently, leading to duplicate data when querying in Elasticsearch.
  fix Upgrade to `swagger-stats` `0.95.18` or later. This version introduces support for Elasticsearch 7.X `flattened` data types, which addresses this issue and improves storage efficiency. Re-index or clear old data in Elasticsearch if needed.

• Authentication not working on /swagger-stats/ux or Hapi authentication issues

  cause Bugs in authentication mechanisms were present in earlier versions for both the built-in UI and Hapi framework integration.
  fix Upgrade to `swagger-stats` `0.99.1` or later, as several authentication-related bugs were fixed in this release, including Hapi-specific issues and general UI protection.

Warnings

• breaking The `prom-client` package was converted from a direct dependency to a peer dependency. You must now explicitly install `prom-client` in your project.
  Fix: Install `prom-client` manually: `npm install prom-client` or `yarn add prom-client`. Ensure its version is within the `>=10 <=14` range specified by swagger-stats.
• gotcha The internal dependency on the deprecated `request` package was replaced with `axios`. While this is an internal change, it's good practice to be aware of dependency updates for security and compatibility.
  Fix: No direct fix for user code, but be aware that if your project had implicit dependencies or complex module resolution tied to `request` being present, this change could subtly affect that setup. Ensure `axios` is compatible within your environment.
• gotcha Version `0.99.1` introduced a full switch to a new UX for the built-in telemetry UI. This might affect custom UI configurations, styling, or expectations of the dashboard layout.
  Fix: Review your `swagger-stats` configuration related to UI customization. If you relied on specific DOM structures or CSS classes for custom branding/integration, these might require updates. Consult the latest documentation for UX configuration options.
• breaking For Elasticsearch 7.X, swagger-stats now supports data type `flattened` for request/response bodies. This is an improvement but implies changes in how data is stored and queried in Elasticsearch, potentially breaking existing Kibana dashboards or queries.
  Fix: If using Elasticsearch for API analytics, review your Kibana visualizations and queries after upgrading to ensure compatibility with the new `flattened` data type. Update existing dashboards as needed, particularly those inspecting request/response body content.

Install

• npm install swagger-stats npm
• yarn add swagger-stats yarn
• pnpm add swagger-stats pnpm

Imports

• swaggerStats
  wrong:

  import { swaggerStats } from 'swagger-stats';

  correct:

  import swaggerStats from 'swagger-stats';
  // Or for CommonJS:
  const swaggerStats = require('swagger-stats');

  The default export is the main swaggerStats object. While the package supports CommonJS, ESM is recommended for new projects.
• swaggerStats.express
  wrong:

  app.use(require('swagger-stats').middleware(options));

  correct:

  import swaggerStats from 'swagger-stats';
  app.use(swaggerStats.express(options));
  // Or for CommonJS:
  const swaggerStats = require('swagger-stats');
  app.use(swaggerStats.express(options));

  Use `swaggerStats.express` (or `swaggerStats.koa`, `swaggerStats.hapi`, etc.) for framework-specific middleware initialization, not a generic `middleware` function.
• swaggerStats.get) (/swagger-stats
  wrong:

  app.get('/swagger-stats', swaggerStats.get());

  correct:

  import swaggerStats from 'swagger-stats';
  app.use(swaggerStats.express({ 
    name: 'my-api',
    uriPath: '/swagger-stats' 
  }));

  The telemetry UI and API endpoints are typically served as part of the middleware initialization (e.g., `swaggerStats.express`), which exposes them on the configured `uriPath`. Direct routing to `swaggerStats.get()` is generally not required for the default UI.

Quickstart

Sets up an Express application with swagger-stats middleware, exposing basic API telemetry, a built-in UI, and Prometheus metrics.

import express from 'express';
import swaggerStats from 'swagger-stats';
import swaggerSpec from './swagger.json'; // Replace with your OpenAPI spec path

const app = express();
const PORT = process.env.PORT || 3000;

// Basic Express route
app.get('/api/hello', (req, res) => {
  res.json({ message: 'Hello from API!' });
});

// Integrate swagger-stats middleware
app.use(swaggerStats.express({
  name: 'My API Service',
  version: '1.0.0',
  swaggerSpec: swaggerSpec, // Optional: Provide your OpenAPI specification
  uriPath: '/swagger-stats', // Default path for UI and metrics
  hostname: 'localhost',
  port: PORT,
  // Uncomment and configure for authentication if needed
  // authentication: true,
  // onAuthenticate: (req, username, password) => {
  //   return username === 'admin' && password === 'admin';
  // },
}));

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Swagger-stats UI available at http://localhost:${PORT}/swagger-stats`);
  console.log(`Prometheus metrics available at http://localhost:${PORT}/swagger-stats/metrics`);
});