Error Monitoring

Scout’s Error Monitoring feature allows you to track, triage, and resolve Python application errors directly within the Scout UI. By integrating with our existing APM agent, we provide enhanced context and filtering capabilities for comprehensive error management.

Installation

AIf you haven't already, set up Scout APM for Python.

BEnable error monitoring by setting the environment variable:

export SCOUT_ERRORS_ENABLED=true

CDeploy!

Once enabled, Scout will automatically begin capturing and organizing errors from your application.

Configuration Options

The following configuration settings are available for error monitoring. These can be set as environment variables with the SCOUT_ prefix or in your application configuration.

Only errors_enabled is required to enable error monitoring. The rest are optional.

Custom Error Reporting

Scout’s error monitoring will automatically capture errors raised on the Django signal got_request_exception and the Celery signal task_failure.

There is no visible effect on your application, and the error will be propagated further on.

However, if an error is caught, the error will never be received by our signal handler. To report this error to Scout use:

import scout_apm.api
scout_apm.api.Error.capture(e)

Ex:

import scout_apm.api
try:
    raise ValueError("Oh No!")
except ValueError as e:
    scout_apm.api.Error.capture(e)

The capture function supports a number of additional parameters to support manually instrumenting other frameworks.

• request_path - The relative path for the request such as: "/test/"
• request_params - A dict representing the query string parameters. This should be JSON-serializable.
• session - A dict representing the session for the request. This should be JSON-serializable.
• custom_controller - A string that is used to identify the controller or job, such as a background task name.
• custom_params - A dict of any additional values that should be included with the error. These will be unassociated with the scout_apm.api.Context. This should be JSON-serializable.

Ex:

from datetime import datetime
import scout_apm.api

# Assume request exists that contains the properties:
# path, session and GET

try:
    raise ValueError("Oh No!")
except ValueError as e:
    scout_apm.api.Error.capture(
        e,
        request_path=request.path,
        request_params=request.GET,
        request_session=request.session,
        custom_controller="broken_view",
        custom_params={"datetime": datetime.utcnow().isoformat()}
    )

Adding Context

Adding context to errors works exactly the same as adding context to web endpoints and background jobs.

If you have already added context to the endpoint or background job where the error has occurred, this context will be shown on the errors page.

Individual Error

To add context to an individual error, such as one that is caught:

import scout_apm.api

try
    raise ValueError("Oh No!")
except ValueError as e:
    scout_apm.api.Context.add("account_id", account.id)
    scout_apm.api.Context.add("user_id", request.user.id)
    scout_apm.api.Error.capture(e)

Visit our custom context section to learn more.

How It Works

Error monitoring is built into the Scout APM Python agent. When an error occurs in your Python application, Scout automatically captures:

• Complete stack trace showing the execution path leading to the error
• Request information including URI, method, and parameters
• Application context including custom context data
• Error grouping based on error type and location

Scout integrates with popular Python frameworks including Django, Flask, FastAPI, and others to capture both handled and unhandled exceptions.

Framework Integration

Django

For Django applications, Scout automatically integrates with Django’s exception handling:

# Django settings.py
INSTALLED_APPS = [
    'scout_apm.django',
    # ... other apps
]

# Enable error monitoring
import os
os.environ['SCOUT_ERRORS_ENABLED'] = 'true'

Flask

For Flask applications:

from scout_apm.flask import ScoutApm
import os

app = Flask(__name__)
os.environ['SCOUT_ERRORS_ENABLED'] = 'true'
ScoutApm(app)

FastAPI

For FastAPI applications:

from scout_apm.fastapi import ScoutMiddleware
import os

app = FastAPI()
os.environ['SCOUT_ERRORS_ENABLED'] = 'true'
app.add_middleware(ScoutMiddleware)

Error Context and Attributes

Scout automatically enriches error data with contextual information:

• Entrypoint: The top-level view or function where the error occurred
• Custom Context: All key-value pairs from any custom context that you have set
• Request Data: HTTP method, URI, parameters, and headers
• Framework Context: Framework-specific context like controller names, etc.

This context makes it easy to understand the circumstances that led to each error occurrence.

Data Retention

Scout retains individual errors for 30 days, and aggregate parent groups (total counts, first seen at (& sha), last error message, etc) indefinitely, providing sufficient time for analysis and resolution tracking. This retention period allows teams to:

• Identify recurring error patterns
• Analyze error trends over time
• Maintain historical context for resolved issues
• Support post-incident analysis and learning

Integration with APM

Error monitoring seamlessly integrates with Scout’s APM features:

• Performance Context: View error occurrences alongside performance traces
• Endpoint Analysis: Identify which endpoints generate the most errors
• Critical Endpoint Errors: Automatically prioritize errors from marked critical endpoints
• Time Correlation: Correlate errors with performance degradation events

For more detailed information on error management features, triage workflows, and team collaboration tools, see the main Error Monitoring documentation.

Not seeing errors?

Reach out to us at support@scoutapm.com for further support and troubleshooting assistance