Python Agent

Python Monitoring is in our tech preview program.

Scout’s Python agent auto-instruments Django and Flask applications, SQL queries, and more. Source code and issues can be found on the scout_apm_python GitHub repository.

Requirements

• Python 2.7 and 3.4+
• Django 1.10+
• Flask 0.10+

Installation

Tailored instructions are provided within our user interface.

Django Installation

General instructions for a Django app:

1	Install the scout-apm package: pip install scout-apm
2	Configure Scout in your settings.py file: # settings.py INSTALLED_APPS = ( 'scout_apm.django', # should be listed first # ... other apps ... ) Scout settings SCOUT_MONITOR = True SCOUT_KEY = “[AVAILABLE IN THE SCOUT UI]” SCOUT_NAME = “A FRIENDLY NAME FOR YOUR APP” If you wish to configure Scout via environment variables, use SCOUT_MONITOR, SCOUT_NAME and SCOUT_KEY instead of providing these settings in settings.py. If you've installed Scout via the Heroku Addon, the provisioning process automatically sets SCOUT_MONITOR and SCOUT_KEY via config vars. Only SCOUT_NAME is required.
3	Deploy.

Flask Installation

General instructions for a Flask app:

1	Install the scout-apm package: pip install scout-apm
2	Configure Scout inside your Flask app: These instructions assume the app uses SQLAlchemy. If that isn't the case, remove the referencing lines. from scout_apm.flask import ScoutApm from scout_apm.flask.sqlalchemy import instrument_sqlalchemy Setup a flask ‘app’ as normal Attaches ScoutApm to the Flask App ScoutApm(app) Instrument the SQLAlchemy handle instrument_sqlalchemy(db) Scout settings app.config[‘SCOUT_MONITOR’] = True app.config[‘SCOUT_KEY’] = “[AVAILABLE IN THE SCOUT UI]” app.config[‘SCOUT_NAME’] = “A FRIENDLY NAME FOR YOUR APP” If you wish to configure Scout via environment variables, use SCOUT_MONITOR, SCOUT_NAME and SCOUT_KEY. If you've installed Scout via the Heroku Addon, the provisioning process automatically sets SCOUT_MONITOR and SCOUT_KEY via config vars. Only SCOUT_NAME is required.
3	Deploy.

It takes approximatively five minutes for your data to first appear within the Scout UI.

Troubleshooting

Not seeing data? Email support@scoutapp.com with:

• A link to your app within Scout (if applicable)
• Your Python version
• Your Django or Flask version

We typically respond within a couple of hours during the business day.

Instrumented Libraries

Scout auto-instruments the following Python libraries:

• Django
  • Middleware
  • Templates (compiling & rendering)
  • Template blocks
  • SQL queries
• Flask

More to come - suggest others in the scout_apm_python GitHub repo.

Configuration Reference

Setting Name	Description	Default	Required
SCOUT_KEY	The organization API key.		Yes
SCOUT_NAME	Name of the application (ex: 'Photos App').		Yes
SCOUT_MONITOR	Whether monitoring data should be reported.	false	Yes

Environment Variables

You can also configure Scout APM via environment variables. Environment variables override settings provided in your settings.py file.

Environment variables use the same configuration names. For example, to set the organization key via environment variables:

export SCOUT_KEY=YOURKEY

Environments

It typically makes sense to treat each environment (production, staging, etc) as a separate application within Scout and ignore the development and test environments. Configure a unique app name for each environment as Scout aggregates data by the app name.

A common approach is to set a SCOUT_NAME environment variable that includes the app environment:

export SCOUT_NAME="YOUR_APP_NAME (Staging)"

This will override the SCOUT_NAME value provided in your settings.py file.

Logging

Django Logging

To log Scout agent output in your Django application, copy the following into your settings.py file:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'stdout': {
            'format': '%(asctime)s %(levelname)s %(message)s',
            'datefmt': '%Y-%m-%dT%H:%M:%S%z',
        },
    },
    'handlers': {
        'stdout': {
            'class': 'logging.StreamHandler',
            'formatter': 'stdout',
        },
        'scout_apm': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            'filename': 'scout_apm_debug.log',
        },
    },
    'root': {
        'handlers': ['stdout'],
        'level': os.environ.get('LOG_LEVEL', 'DEBUG'),
    },
    'loggers': {
        'scout_apm': {
            'handlers': ['scout_apm'],
            'level': 'DEBUG',
            'propagate': True,
        },
    },
}

Flask Logging

Add the following your Flask app:

dictConfig({
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'stdout': {
            'format': '%(asctime)s %(levelname)s %(message)s',
            'datefmt': '%Y-%m-%dT%H:%M:%S%z',
        },
    },
    'handlers': {
        'stdout': {
            'class': 'logging.StreamHandler',
            'formatter': 'stdout',
        },
        'scout_apm': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            'filename': 'scout_apm_debug.log',
        },
    },
    'root': {
        'handlers': ['stdout'],
        'level': os.environ.get('LOG_LEVEL', 'DEBUG'),
    },
    'loggers': {
        'scout_apm': {
            'handlers': ['scout_apm'],
            'level': 'DEBUG',
            'propagate': True,
        },
    },
})

If LOGGING is already defined, merge the above into the existing Dictionary.

Custom Context

Context lets you see the forest from the trees. For example, you can add custom context to answer critical questions like:

• How many users are impacted by slow requests?
• How many trial customers are impacted by slow requests?
• How much of an impact are slow requests having on our highest paying customers?

It’s simple to add custom context to your app:

# ScoutApm.Context.add(key,value)
ScoutApm.Context.add("user_email",request.user.email)

Context Key Restrictions

The Context key must be a String with only printable characters. Custom context keys may contain alphanumeric characters, dashes, and underscores. Spaces are not allowed.

Attempts to add invalid context will be ignored.

Context Value Types

Context values can be any json-serializable type. Examples:

• "1.1.1.1"
• "free"
• 100

Updating to the Newest Version

pip install scout-apm --upgrade

The package changelog is available here.