Customer StoriesReadMe Blog

Any issues?

Integrations can be tricky! [Contact support](🔗) if you have any questions/issues.

## Overview

If you're a developer, it takes a few small steps to send your API logs to [ReadMe](🔗) so your team can get deep insights into your API's usage with [ReadMe Metrics](🔗). Here's an overview of how the integration works:

<!-- TODO: we should rename these options! -->

<!--alex ignore blacklist whitelist-->

  • You add the 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 Metrics, 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`:


  1. In the root of your project install the new gem:

  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 `api_key`:

It also requires a block which should return a hash describing the user generating the request/response. These values should be fetched from the user making the request:

User Identification
We use the `email` you send us via grouping for user identification and company association. While email is not require, to get the best value out Metrics, we highly recommend that you include it.
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.


Additional you can also send the following two optional pieces of data within this payload:
<!-- prettier-ignore-start -->
ParameterTypeDescription
`log_id`stringA UUIDv4 identifier. If not provided this will be automatically generated for you. Providing your own `log_id` is useful if you want to know the URL of the log in advance, i.e. `{your_base_url}/logs/{your_log_id}`.
`ignore`boolA flag that when set to `true` will suppress sending the log.
<!-- prettier-ignore-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:
<!-- prettier-ignore-start -->
OptionTypeDescription
`development`boolDefaults to `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`intBy 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`Array of stringsAn array of strings representing keys from your API requests' and responses' bodies and headers that you wish to omit from sending to ReadMe.<br /><br />You may only configure either `reject_params` or `allow_only` at one time.<br /><br />`reject_params: ["Authorization", "password"]`
`allow_only`Array of stringsAn 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.<br /><br />You may only configure either `reject_params` or `allow_only` at one time.
`logger`LoggerA 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. By default we have a `Logger` in place that logs to `stdout`.
<!-- prettier-ignore-end -->
## Sample Applications
  • [Rails](🔗)