ReadMe Metrics SDK for Node.js

Common errors

• Error: You must provide an API key. Please visit https://dash.readme.com/project/YOUR_PROJECT/v1.0/api-metrics to get one.

  cause The `apiKey` option was not provided or was empty during the `Metrics` class instantiation.
  fix Ensure `apiKey` is passed to the `Metrics` constructor, typically from an environment variable (e.g., `new Metrics({ apiKey: process.env.README_API_KEY })`).

• TypeError: (0 , readmeio__WEBPACK_IMPORTED_MODULE_0__.Metrics) is not a constructor

  cause This error often occurs in bundled environments (like Webpack or Vite) when mixing CommonJS `require` semantics with ESM `import` syntax, or incorrectly trying to import a named export as a default export.
  fix Ensure you are using `import { Metrics } from 'readmeio';` for named imports. Verify your bundler configuration correctly handles ESM and CJS interop, especially if your project is `type: 'module'`.

• TypeError: metrics.log is not a function

  cause The `metrics` object was not correctly instantiated, or `log` was called before the object was fully initialized.
  fix Double-check that `new Metrics({ ... })` was successfully called and that the resulting instance is available when `log` is invoked. Ensure there are no asynchronous initialization issues preventing `metrics` from being assigned.

• ERR_REQUIRE_ESM

  cause Attempting to use `require('readmeio')` in a pure ESM context (e.g., in a Node.js project with `"type": "module"` in `package.json` where `readmeio` might not provide a CommonJS entry point for that specific environment).
  fix Migrate your import statements from `const { Metrics } = require('readmeio');` to `import { Metrics } from 'readmeio';`. Ensure your project and build tools are configured to handle ESM.

Warnings

• gotcha Always protect your `apiKey` and ensure it's not exposed client-side or committed directly into source control. Use environment variables (e.g., `process.env.README_API_KEY`) and secure secret management practices.
  Fix: Store `apiKey` in environment variables and access them securely at runtime. Never hardcode sensitive credentials.
• gotcha Improperly configured `redact` options can lead to sensitive data (like PII, authentication tokens, or internal IDs) being sent to ReadMe.com. Thoroughly test your redaction rules.
  Fix: Carefully define `redact.headers` and `redact.body` arrays to include all sensitive fields. Regularly audit the data sent to ReadMe.com to confirm redaction is working as intended.
• gotcha The SDK buffers logs and sends them in batches. If your application terminates abruptly without calling `metrics.sendQueue()`, some logs might be lost. This is particularly relevant in serverless or short-lived processes.
  Fix: Ensure `metrics.sendQueue()` is called during application shutdown hooks (e.g., `SIGINT`, `SIGTERM` handlers in Node.js, or before a serverless function completes) to flush any pending metrics. Handle potential `sendQueue` failures gracefully.
• breaking While Node.js >=14 supports both CommonJS and ESM, future major versions of this SDK (or Node.js itself) may enforce ESM-only. Relying solely on `require()` could lead to breaking changes.
  Fix: Adopt ESM `import` syntax for all package imports. If using TypeScript, ensure your `tsconfig.json` is configured for `module: 'Node16'` or `module: 'ES2022'` and `moduleResolution: 'Node16'` or `Bundler`.

Install

• npm install readmeio npm
• yarn add readmeio yarn
• pnpm add readmeio pnpm

Imports

• Metrics
  wrong:

  const Metrics = require('readmeio');

  correct:

  import { Metrics } from 'readmeio';

  The `Metrics` class is the primary entry point for manual API logging. While CommonJS `require` might work in some environments due to Node.js 14+ compatibility layers, ESM `import` is the recommended and more modern approach, especially in TypeScript projects.
• expressMiddleware
  wrong:

  const expressMiddleware = require('readmeio').expressMiddleware;

  correct:

  import { expressMiddleware } from 'readmeio';

  This named export provides a convenient middleware function for Express.js applications. Prefer destructuring for named exports. Direct property access on `require()` is a CommonJS pattern.
• MetricsOptions
  wrong:

  import { MetricsOptions } from 'readmeio';

  correct:

  import type { MetricsOptions } from 'readmeio';

  For type definitions in TypeScript, use `import type` to ensure they are removed during compilation, preventing potential runtime issues and ensuring proper tree-shaking.

Quickstart

Demonstrates how to initialize the ReadMe Metrics SDK, create a basic HTTP server, and log simulated API requests and responses, including data redaction for sensitive fields, to the ReadMe.com dashboard. Includes graceful shutdown.

import { Metrics } from 'readmeio';
import http from 'http';

// Initialize the ReadMe Metrics SDK
// In a real application, retrieve process.env.README_API_KEY and process.env.NODE_ENV securely
const metrics = new Metrics({
  apiKey: process.env.README_API_KEY ?? 'your_readme_api_key_here',
  development: process.env.NODE_ENV !== 'production',
});

// Create a simple HTTP server to simulate API calls
const server = http.createServer(async (req, res) => {
  // Simulate an incoming request
  const requestBody = { user: 'testuser', data: 'some data', sensitive_id: '12345' };
  const requestHeaders = {
    'content-type': 'application/json',
    'x-api-key': 'super-secret-internal-key', // Example of a header that might be redacted
    'user-agent': 'node-http-client',
  };

  // Simulate an outgoing response
  const responseBody = { status: 'success', message: 'Hello from API', internal_ref: 'xyz' };
  const responseHeaders = {
    'content-type': 'application/json',
    'x-response-id': 'uuid-12345',
  };

  // Log the request and response to ReadMe
  try {
    await metrics.log({
      // Full URL is important for ReadMe metrics to categorize endpoints
      url: new URL(`http://localhost:3000${req.url}`),
      method: req.method ?? 'GET',
      api: {
        key: 'user-id-123', // Identifier for the user making the API call
        // label: 'Optional label for this user/API key'
      },
      // Redaction example: prevent 'x-api-key' header from being sent to ReadMe
      // and prevent 'user' field in request body
      redact: {
        headers: ['x-api-key'],
        body: ['user', 'sensitive_id'],
      },
      request: {
        headers: requestHeaders,
        body: JSON.stringify(requestBody),
      },
      response: {
        status: 200,
        headers: responseHeaders,
        body: JSON.stringify(responseBody),
      },
    });
  } catch (error) {
    console.error('Failed to log metrics:', error);
  }

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(responseBody));
});

server.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Send a request, e.g., curl http://localhost:3000/api/test');
  console.log('Check your ReadMe.com dashboard for metrics.');
});

// Example of how to shut down cleanly
process.on('SIGINT', () => {
  console.log('Shutting down server...');
  server.close(async () => {
    // Ensure any buffered logs are sent before exiting
    try {
      await metrics.sendQueue();
      console.log('Buffered logs sent.');
    } catch (error) {
      console.error('Failed to send remaining logs:', error);
    }
    console.log('Server gracefully shut down.');
    process.exit(0);
  });
});