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
- Add the gem to your projects Gemfile
gem "readme-metrics"
- In the root of your project install the new gem
bundle install
- Configure the middleware in your
development.rb
andproduction.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
|
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. |
Updated 6 months ago