Install

The Python Agent takes the form of a module named appoptics_apm that provides middleware for common frameworks. Install the module, plug it into your application, and get visibility.

Dependencies

The agent compiles an extension during install, thus you’ll need to have the following on the system prior to installing the agent:

  • python header files
  • the gnu compiler
  • the make command

Note that some systems may provide multiple python versions, in which case you would need to specify the versioned header package such as python3-dev that matches the python runtime.

On Debian/Ubuntu:

$ sudo apt-get install python-dev g++ make

On RHEL/CentOS/Amazon Linux:

$ sudo yum install python-devel gcc-c++ make

On Alpine:

$ sudo apk add python-dev g++ make

You can check the support matrix to make sure your system is supported.

Getting the Agent

First, install the package into your application’s environment:

$ pip install appoptics-apm

Now the module appoptics_apm should be available, see below on how to enable it for your application.

Enabling the Agent

The agent requires a service key to connect to your account, and must be either attached as a middleware or through custom instrumentation to your application. Read below to get set up.

Service key

The service key should be defined in the environment your application runs in (see Configuration):

$ export APPOPTICS_SERVICE_KEY="api-token-here:your-service-name-eg-python"

A service key is composed of an API token with write permisisons and the name of the service you’re installing on. Our onboarding flow provides the full service key, or check the API Tokens page to grab a token and fill the service name yourself.

Application Middleware

Instructions are provided for common frameworks below. If you don’t find what you need, you can always use custom instrumentation to monitor any Python process.

Django

Add the following import to your django settings.py as well as your WSGI file, if you have one:

from appoptics_apm import djangoware

If you’re deploying with uWSGI and are specifying the WSGI handler module as django.core.handlers.wsgi:WSGIHandler(), you can use our handler module instead, which is a drop-in replacement. Just specify appoptics_apm.djangoware:AppOpticsApmWSGIHandler() and you won’t need to modify your settings.py. Below is an example uWSGI .ini config file for a django 1.11 project located at /deploy/django/mysite:

[uwsgi]
http-socket = 127.0.0.1:9000
chdir = /deploy/django/
wsgi-file = mysite/wsgi.py
env = DJANGO_SETTINGS_MODULE=mysite.settings
env = APPOPTICS_SERVICE_KEY=<your service key here>
module = appoptics_apm.djangoware:AppOpticsApmWSGIHandler()

Alternately you can modify the wsgi.py script to use the agent’s WSGI handler for django, an example:

import django
import os
from appoptics_apm import djangoware

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
django.setup()
application = djangoware.AppOpticsApmWSGIHandler()

Tornado

1. Import Django instrumentation library:

from appoptics_apm import tornado_oboe
  1. Make your handler function inherit from tornado_oboe.AppOpticsApmBaseHandler:
class MainHandler(tornado_oboe.AppOpticsApmBaseHandler):
    def get(self):
        logging.error("Inside Main Handler %s", appoptics_apm.Context.get\_default())
        self.write("Hello, world from %s:" % appoptics_apm.Context.get\_default())
        self.finish()

...

tornado.options.parse_command_line()

application = tornado.web.Application([
    (r"/", MainHandler),
    ], **settings)

application.listen(options.port)
tornado.ioloop.IOLoop.instance().start()

Flask and Generic WSGI

Many python apps are implemented atop WSGI, which provides a uniform interface through which web frameworks and middleware libraries interoperate. AppOptics offers a WSGI middleware component called AppOpticsApmMiddleware, which wraps your WSGI app to collect performance statistics. Install middleware instrumentation as you would any other middleware by adding it to the file that instantiates your app. But put it at the end of the list, closest to the outside of the middleware stack.

The following code demonstrates the instrumentation of Flask applications. Applications using other frameworks can also wrap the WSGI app with AppOpticsApmMiddleware class to trace the web requests.

# flask example
from flask import Flask
from appoptics_apm.middleware import AppOpticsApmMiddleware

# the flask app
app = Flask(__name__)

app.wsgi_app = AppOpticsApmMiddleware(app.wsgi_app)

@app.route("/")
def hello():
    return "Hello World!"

Now start your application and make some requests, check your AppOptics dashboard and you will find the trace events reported from your application.