ReadMe Documentation

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

Ruby (Rails/Rack) + API Metrics

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 Rails application.
  • 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.

Getting Started

  1. Add the gem to your projects Gemfile
gem "readme-metrics"
  1. In the root of your project install the new gem
bundle install
  1. Configure the middleware in your development.rb and production.rb files:

The Readme::Metrics class takes an options hash argument that should at least contain and api_key key:

{ api_key: "<<user>>" }

It also requires a block which should return a hash describing the user generating the request/response. These values maybe be fetched from the environment or hard-coded:

{ id: "user-id", label: "User Name", email: "[email protected]" }

In the examples below, the Rails application is using a warden-based authentication gem (e.g., Devise), so the user can be fetched via the WardenProxy stored in the environment.

require "readme/metrics"

options = {
  api_key: "<<user>>",
  development: true
}

config.middleware.use Readme::Metrics, options do |env|
  current_user = env['warden'].authenticate

  if current_user.present?
    {
      id: current_user.id,
      label: current_user.name,
      email: current_user.email
    }
  else
    {
      id: "guest",
      label: "Guest User",
      email: "[email protected]"
    }
  end
end
require "readme/metrics"

options = { api_key: "<<user>>" }

config.middleware.use Readme::Metrics, options do |env|
  current_user = env['warden'].authenticate

  if current_user.present?
    {
      id: current_user.id,
      label: current_user.name,
      email: current_user.email
    }
  else
    {
      id: "guest",
      label: "Guest User",
      email: "[email protected]"
    }
  end
end

Configuration options

There are a few options in addition to api_key you can pass in to change how the logs are sent to ReadMe. These are all optional:

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

buffer_length

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

reject_params

An array of strings representing keys from your API requests' and responses' bodies and headers that you wish to omit from sending to ReadMe.

You may only configure either reject_params or allow_only at one time

reject_params: ["Authorization", "password"]

allow_only

An array of strings representing keys from your API requests' and responses' bodies and headers that you only wish to send to ReadMe. All other keys will be omitted

You may only configure either reject_params or allow_only at one time

logger

default: Logger logging to stdout A logger class that conforms to the same interface as Logger or RailsLogger. Pass this option in if you have some custom logging solution and you want to send logs from the middleware to the same location.


Did this page help you?