Scout APM Python Agent

3.5.3 · active · verified Thu Apr 16

Scout APM is an Application Performance Monitoring (APM) agent for Python that provides detailed performance metrics and transaction traces for web applications (Django, Flask, FastAPI, etc.) and background jobs (Celery, RQ). It helps identify performance bottlenecks, monitor errors, manage logs, and track external services. The current stable version is 3.5.3, with regular updates to support new Python versions and frameworks.

Common errors

```
Not seeing data in Scout APM UI after installation.
```
cause Common causes include incorrect API key or application name, `monitor` flag set to `False`, network issues preventing connection to the Scout APM collector, or the agent not being installed or initialized early enough in the application lifecycle. Python version incompatibility with `scout-apm` is also a possibility.

fix 1. Verify `SCOUT_KEY` and `SCOUT_NAME` are correct. 2. Ensure `SCOUT_MONITOR` is set to `True` (or 'true' via env var). 3. Enable debug logging (`logging.getLogger("scout_apm").setLevel(logging.DEBUG)`) and check logs for errors or connection issues. 4. Ensure `install()` is called at application startup. 5. Confirm your Python version is 3.8+.
```
ModuleNotFoundError: No module named 'scout_apm.django'
```
cause This error often occurs when trying to directly `import scout_apm.django` or use it as a class, while Django integration primarily relies on adding `'scout_apm.django'` to your `INSTALLED_APPS` in `settings.py`.

fix For Django applications, add `'scout_apm.django'` to the `INSTALLED_APPS` list in your `settings.py` file. No direct import statement for `scout_apm.django` is typically needed in your code.

Warnings

breaking Python 2.7 and early Python 3 versions (prior to 3.8) are no longer supported by recent `scout-apm` versions. Attempts to run with unsupported Python versions will fail or result in incomplete monitoring.
Fix: Upgrade your Python environment to 3.8 or newer. If stuck on legacy Python, pin `scout-apm` to version `<=2.26.1`.
gotcha Avoid dynamically generating high-cardinality transaction names (e.g., including user IDs or highly variable data). This can lead to excessive unique transactions, impact UI performance, and may result in rate limiting of data.
Fix: Use a limited set of descriptive transaction names. For high-dimensionality data, add it as context to the transaction instead of making it part of the transaction name. Example: `api.Context.set(user_id=user.id)`.
deprecated Several configuration options were renamed in previous major versions. `log_level` was renamed to `core_agent_log_level` (pre 2.6.0) and `config_file` to `core_agent_config_file` (pre 2.13.0). The `ignore` configuration for URL paths was replaced by `ignored_endpoints`.
Fix: Use the new configuration names (`core_agent_log_level`, `core_agent_config_file`, `ignored_endpoints`). Old names might still work as aliases but are not recommended for new configurations.

Install

pip install scout-apm Install latest version

Imports

Config
```
from scout_apm.api import Config
```
Used for global configuration via API.
WebTransaction
```
from scout_apm.api import WebTransaction
```
Used for custom web transaction instrumentation.
BackgroundTransaction
```
from scout_apm.api import BackgroundTransaction
```
Used for custom background job instrumentation.
instrument
```
from scout_apm.api import instrument
```
Used for custom timing instrumentation within a transaction.
ScoutApm (Flask)
```
from scout_apm.flask import ScoutApm
```
Specific Flask integration class.
Django integration
wrong:
```
from scout_apm.django import ScoutApm
```
correct:
```
INSTALLED_APPS = ['scout_apm.django', ...]
```
Django integration is typically configured via INSTALLED_APPS, not direct import and instantiation.

Quickstart

The quickstart demonstrates global configuration via `scout_apm.api.Config.set()` and agent installation via `scout_apm.api.install()`. It also includes an example of custom instrumentation using `WebTransaction` and `instrument` for non-framework specific code. In production, `SCOUT_KEY`, `SCOUT_NAME`, and `SCOUT_MONITOR` are commonly set via environment variables.

import os
from scout_apm.api import Config, install

# Configure Scout APM (often done via environment variables in production)
# For local testing, ensure these are set in your environment or replace os.environ.get with actual values.
Config.set(key=os.environ.get('SCOUT_KEY', 'YOUR_SCOUT_KEY'),
           name=os.environ.get('SCOUT_NAME', 'My Python App'),
           monitor=os.environ.get('SCOUT_MONITOR', 'True').lower() == 'true')

# Install the agent (should be called early in your application startup)
install()

# Example of custom instrumentation (e.g., in a non-web script or job)
from scout_apm.api import WebTransaction, instrument

def my_complex_function():
    with instrument('MyCustomOperation'):
        # Simulate some work
        sum(range(1000000))
    return 'Operation complete'

if __name__ == '__main__':
    # In a web framework, transactions are typically auto-instrumented.
    # For custom scripts or background jobs:
    with WebTransaction('MyScriptExecution'):
        print(my_complex_function())

view raw JSON →