Developer Metrics

ReadMe Documentation

Welcome to the ReadMe Documentation, where you'll find comprehensive guides and community support to help you start working with ReadMe as quickly as possible!

Get Started

Node.js (Express) + API Metrics

Any issues?

Integrations can be tricky! Contact support if you have any questions/issues.

Overview

If you're a developer, it's super easy to send your API logs to ReadMe, so your team can get deep insights into your API's usage. Here's an overview of how the integration works:

  • You add ReadMe middleware to your Express server.
  • The middleware sends to ReadMe the request and response objects that your Express server generates each time a user makes a request to your API. The entire objects are sent, unless you blacklist or whitelist keys.
  • ReadMe extracts information to display in the API Metrics Dashboard, such as which endpoint is being called, response code, and error messages. It also identifies the customer who called your API, using whichever keys in the middleware you call out as containing relevant customer info.

Steps

Note these steps assume you are working in Node.js and Express:

  1. Locate the file in your company's API codebase that contains your Express server. Often this file is named express.js or app.js. You can also search on the code snippet express()

  2. From the directory of this codebase, run the following command in your command line to install the readmeio package from npm:

npm install readmeio --save
  1. Load the readmeio module into your Express server. Usually near the beginning of the file, you will see several require statements. Add the following statement to that group:
const readme = require('readmeio');
  1. Configure the following middleware function:
app.use(readme.metrics('', req => ({
  id: req.<userId>,
  label: req.<userNameToShowInDashboard>,
  email: req.<userEmailAddress>,
})));

The readme.metrics middleware takes the following parameters:

  • The ReadMe API Key
  • A function that takes the req object and returns an object describing the user (in the case above, it just returns their apiKey to identify the caller)
  • An options function that is not shown in the preceding middleware, but is discussed below.

Minimal middleware configuration

Here's the bare minimum you need to configure:

  • The ReadMe API Key: The first parameter that readme.metrics takes is your doc project's ReadMe API Key. If you're logged in to these docs, this string is automatically populated in the proceeding middleware code. Otherwise, copy and paste it in from dash.readme.com/project/<yourProject>/v<yourVersion>/api-key.

  • API caller identification: To identify the API caller, replace <userId>, <userNameToShowInDashboard>, and <userEmailAddress> with the appropriate properties in your req object that contain your user data. More details follow in the next section.

  1. Paste the configured middleware into the file containing your Express server. Note that this middleware is not likely to be sensitive to order, so you can put it anywhere in the file after middleware that adds user properties to the request object. If you are new to Express, see How to Write Middleware for Express.js Apps

Identifying the API Caller

There are three fields that you can use to identify the user making the API call. We recommend passing all three to readme.metrics to make API Metrics as useful as possible. (If your req object doesn't have all this information, we recommend adding it via additional middleware prior to this.)

app.use(readme.metrics('', req => ({
  id: req.<userId>,
  label: req.<userNameToShowInDashboard>,
  email: req.<userEmailAddress>,
})));
Field
Usage

id

Required Unique identifier for the caller. This can be anything that is unique, such as an id of this user in your database

label

This will be the user's display name in the API Metrics Dashboard, since it's much easier to remember a name than a unique identifier.

email

Email of the user that is making the call

Configuration Options

There are a few options you can pass in to change how the logs are sent to ReadMe. These are passed in an object as the third parameter to the readme.metrics.

const readme = require('readmeio');
const env = process.env.NODE_ENV;

app.use(readme.metrics('', req => ({
  id: req.<userId>,
  label: req.<userNameToShowInDashboard>,
  email: req.<userEmailAddress>,
}), {
  development: env !== 'production',
  bufferLength: 1,
  blacklist: <sensitiveKeysToOmit>,
  whitelist: <keysOnlyToSend>,
}));
Option
Use

development

default: false If true, the log will be separate from normal production logs. This is great for separating staging or test data from data coming from customers

bufferLength

default: 10 By default, we only send logs to ReadMe after 10 requests are made. Depending on the usage of your API it make make sense to send logs more or less frequently

blacklist

An array of keys from your API requests and responses that you wish to blacklist from sending to ReadMe.*

If you configure a blacklist, it will override any whitelist configuration.

whitelist

An array of keys from your API requests and responses that you only wish to send to ReadMe.*

  • Note: Blacklist/whitelist configuration does not support dot-notation, so you can only blacklist or whitelist top-level keys.

Updated 8 days ago


Node.js (Express) + API Metrics


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.