Name: librato-python-web
Owner: Librato
Description: Report key app statistics to the Librato Metrics service
Created: 2015-11-11 22:12:44.0
Updated: 2016-08-18 21:19:49.0
Pushed: 2016-08-26 16:30:36.0
Homepage: null
Size: 358
Language: Python
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
librato-python-web is the Python agent for Librato's Django, Flask, CherryPy and Gunicorn turnkey integrations. It gathers essential health and performance metrics related to your web application and ships them to Librato, where you can view them in curated or custom metrics dashboards.
See the following KB articles for a general overview of how to create a turnkey Librato integration and configure the Python agent.
We highly recommend running your instrumented application under a virtual environment. E.g.
install virtualenv
ualenv my_project_folder
ce my_project_folder/bin/activate
Install the Python agent using pip as shown below.
install librato-python-web
Use the provided librato-launch tool to configure the Python agent. Do this for every web application that you want to monitor. For example, the following command configures the Python agent to monitor a cherrypy application called 'cherrypy-prod-1'.
ato-config --app-id cherrypy-prod-1 --integration=cherrypy --user user@librato.com --api-token XXXXXXXXXXXX
This will create a JSON configuration file in the current directory, named agent-conf.json, which looks as follows.
integration": "cherrypy",
metrics_hostname": "metrics-api.librato.com",
hostname": "localhost",
stop": false,
app_id": "cherrypy-prod-1",
no_aggregate_counters": false,
pidfile": "/var/run/solarwinds-python-statsd.pid",
flush_interval": 10000,
daemonize": false,
user": "user@librato.com",
expire": 0,
api_token": ?XXXXXXXXXXXX?,
debug": false,
pct": 95,
port": 8142,
restart": false
–config-path can be optionally used to specify an alternate file location. Default is './agent-conf.json'.
–integration optionally specifies the web framework to monitor (default is 'django').
–app-id (required) specifies a unique identifier for the application. The instrumentation prefixes the application id to the source for every measurement related to the app. This allows you to filter or aggregate metrics down to the application in turnkey or custom dashboards.
Run `librato-config --help` to see a full list of options.
In order to instrument your application, prefix your runtime command with librato-launch. E.g.
ato-launch python manage.py runserver
Running with librato-launch installs a custom module loader, which instruments classes as they get imported by the application. The loader targets framework modules (e.g. django.*) to report web request latency, throughput and error metrics. It also instruments libraries such as mysql, postgres, elasticsearch, urllib2 and requests in order to decompose web request latency into 'data', 'external', 'wsgi' and 'app' buckets.
librato-launch consumes the configuration file (./agent-conf.json, by default). Use –config-path to override this default location.
librato-launch spawns a StatsD process to report metrics to Librato, which listens over UDP port 8142 by default. You can customize this port using the –port option to librato-config, or by manually editing the 'port' option in the configuration file.
The following environment variables, if defined, will override any configuration file settings.
To monitor Gunicorn, add the –statsd-host option as shown below.
ato-launch gunicorn --statsd-host=127.0.0.1:8142 ... my_module:my_app
You can't or don't want to auto-instrument your app, you can skip librato-launch and trigger instrumentation using the following code.
librato_python_web.instrumentor import bootstrap
strap.init(config-file-path) # config-file-path can be omitted and defaults to './agent-conf.json'
Since modules are instrumented as they are loaded, it is important to call bootstrap.init() before the web framework (e.g. Django) and dependencies such as mysql or postgres are imported.
Since librato-launch is no longer in the picture, you'll need to run the StatsD server in order to report measurements to Librato. This can be done using the following command.
ato-statsd-server
ato-statsd-server --config-path <config-file-location>
Run `librato-statsd-server --help` for a complete list of options.
One of the web frameworks (django, flask or cherrypy) gets instrumented depending on the 'integration' configuration file option. By default, The following additional libraries are instrumented, if imported by the application.
| Library | Tested version(s) | Comments | |—————|——————–|—————–| | gunicorn | 19.4.5 | | | sqlite3 | | | | MySQL-python | 1.2.5 | | | psycopg2 | 2.6.1 | Postgres | | elasticsearch | 2.2.0 | | | pykafka | 2.2.1 | | | urllib2 | | Python 2.x only | | requests | 2.9.1 | | | logging | | |
The 'libraries' option can be used to exclude libraries (e.g. to zero in on a version compatibility issue). For example, appending the following line to the configuration file causes postgres, elasticsearch and urllib2 to be ignored.
"libraries": ["gunicorn", "sqlite3", "MySQL-python", "requests", "logging"]
You can turn on verbose logging using the 'instrumentor.log_level' configuration file option. 10 means debug, 20 means info, 30 means warning and so on. The default logging level is 30 (warning). Append the following line to the configuration file to turn on verbose debugging.
"instrumentor.log_level": 10
This should be done during troubleshooting only to avoid a performance degradation.
Copyright (c) 2015 Librato Inc. See LICENSE for details.