Python (Flask) Setup

🚧

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:

• You install the ReadMe Flask extension and configure it in your Flask application.
• You write a grouping function, which is used to tie each API request to the user or API key that initiated the request.
• The extension will send to ReadMe the request and response objects that your server generates each time a user makes a request to your API. The entire objects are sent, unless you deny or allow specific keys from the request.
• 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 the data returned by your grouping function.

Steps

1. From the directory of your codebase, run the following command in your command line to install the Flask variant of the readme-metrics package from pypi. You can also add this to your requirements.txt file.

pip install "readme-metrics[Flask]"

2. In your codebase, write a grouping function to inform ReadMe of the user or API key holder that is responsible for a given request. The grouping function receives the current Flask Request object as input, and should return a data structure describing the current user or API key holder. A basic grouping function would look like this:

def grouping_function(request):
    # You can lookup your user here, pull it off the request object, etc.
    # Your grouping function should return None if you don't want the request
    # to be logged, and otherwise return a structure like the one below.
    if user_is_authenticated:
        return {
            "api_key": "unique api_key of the user",
            "label": "label for us to show for this user (account name, user name, email, etc)",
            "email": "email address for user"
        }
    else:
        return None

3. Set up the extension wherever you initialize your Flask app.

from flask import Flask
from readme_metrics import MetricsApiConfig
from readme_metrics.flask_readme import ReadMeMetrics

# You already have code to create a Flask app...
app = Flask("Your-App-Name")

# Just add code to create the ReadMeMetrics extension and connect it to your app.
metrics_extension = ReadMeMetrics(
    MetricsApiConfig(
        api_key="<<user>>",
        grouping_function=path.to.your.grouping_function
    )
)
metrics_extension.init_app(app)

The MetricsApiConfig object takes the following parameters:

• Your ReadMe API Key. If you're logged in to these docs, this string is automatically populated in the preceeding code.
• A function that takes the Request object and returns a dict describing the user, or None if the request should not be logged
• Additional options: see details below

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 make API Metrics as useful as possible.

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 first parameter to ReadMeMetrics extension constructor.

metrics_extension = ReadMeMetrics(
    MetricsApiConfig(
        api_key="KEYS:USER",
        grouping_function=path.to.your.grouping_function,
        buffer_length=1,
        background_worker_mode=False,
        allowlist=["city", "state", "postal_code", "country"],
        timeout=15
    )
)