Flask-Kadabra¶

Initialization¶

You can initialize the Kadabra object directly:

from flask import Flask
from flask_kadabra import Kadabra

app = Flask()
kadabra = Kadabra(app)

Or, you can defer the installation if you are utilizing the flask:patterns/appfactories pattern, using the init_app() method:

from flask import Flask
from flask_kadabra import Kadabra

kadabra = Kadabra()

def create_app():
    app = Flask()
    kadabra.init_app(app)

You can configure the underlying Kadabra client API by passing a dictionary as the second argument to the Kadabra constructor:

config = {
    'CLIENT_CHANNEL_ARGS': {
        'port': 6500
    }
}

app = Flask()
kadabra(app, config)

For more information about how to configure the client API, see Kadabra’s Configuration documentation.

There are also some configuration values you can specify for your Flask application object to change the behavior of the Kadabra object. For more info, check out Configuration.

Enabling Metrics for Your Routes¶

To record metrics for API requests to one of your routes, simply use the record_metrics decorator:

@api.route('/')
@record_metrics
def index():
    return "Hello, World!"

This will record the request time in milliseconds (as a timer called “RequestTime”), whether the HTTP status code of the response was a server error (as a counter called “Failure” with a value of 0 or 1), and whether the HTTP status code of the response was a client error (as a counter called “ClientError” with a value of 0 or 1). For more information on counters and timers, see Collecting Metrics.

These metrics will be grouped under a “Method” dimension whose value is the name of your view function, as well as any additional dimensions you’ve specified for the CLIENT_DEFAULT_DIMENSIONS key in Kadabra’s configuration (see Configuration).

Additionally, a metrics attribute will be added to Flask’s g object. This exposes the underlying MetricsCollector API which allows you to add counters and timers in your application code. They will be grouped under the same dimensions as the request time, failure, and client error metrics.

Instrument Your Code with Additional Metrics¶

Using g.metrics you can record additional metrics from your application code. For example, if one of your APIs calls an external third-party service you may want to time the call:

start = datetime.datetime.utcnow()
response = requests.get(...) # External call
end = datetime.datetime.utcnow()
g.metrics.set_timer("ExternalCallTime", end - start)

Any metrics you record in the context of a request being executed will be grouped together under the same dimensions, meaning the same “Method” and any other dimensions you set via the CLIENT_DEFAULT_DIMENSIONS configuration key or elsewhere in your application code.

You can control aspects of how your Flask app uses Kadabra via Configuration.

Infrastructure Management¶

In the modern era, you will want to make it as easy to deploy your application as possible. You don’t want to be manually installing your dependencies, starting the Redis server, kicking off your application, and so on for every deployment. In addition to saving developer pain, this also helps prevent bugs from being introduced during deployment time, and makes it simple to deploy to different environments and cloud providers. Furthermore, you don’t want to have to manually restart processes when they inevitably fail; your infrastructure management system should take care of process management for you.

Options include configuration management and orchestration tools such as Puppet, Chef, and Ansible. Personally I like to deploy my applications as containers using Docker. Whatever tool you use, you’ll want to be sure that metrics flow from your application to the publisher destination of your choice.

The Full Stack¶

I think of my basic Flask application (say, one that talks to a SQL database) in five components:

1. The Flask application code itself
2. The HTTP webserver to serve the Flask application (typically gunicorn running locally)
3. The reverse proxy that will listen to external requests and proxy them to gunicorn (typically nginx)
4. A local Redis server for queueing metrics to be published and as a cache if needed
5. The Kadabra Agent for publishing metrics

Additionally I usually run an InfluxDB server that can only be accessed by my webserver hosts, which will publish metrics to that server.

Because I use Docker, I typically author a simple compose file with a service for each of the components above. A thorough treatment of “dockerizing” the entire stack is beyond the scope of this section, but the agent is worth talking about.

Running the agent basically consists of configuring it and calling the start() method. You can use the code from Getting Started and just run it in a dedicated Python process, with the possible addition of configuration e.g. if your Redis server is refered to as something other than localhost.

You will want to run this process under some sort of a process management system, at a minimum something like supervisord but ideally a more robust system like Docker. In my compose file I use the command configuration key with something like python run.py, where run.py contains the agent code. The agent is designed to respond gracefully to shutdown signals like SIGINT and SIGTERM, and will try to make sure there are no metrics that haven’t yet been published before shutting down.