Google App Engine

Recording Exceptions with ereporter

Eric Higgins
April 2010

In the words of Professor Farnsworth: "Good news, everyone!". Using the google.appengine.ext.ereporter package available in the App Engine SDK, developers can receive exception reports from their applications by email.

Here's an example of a typical exception being logged.

try:
  db.put(models)
except (db.Timeout, db.InternalError):
  logging.exception('Some or all of the models could not be written.')

If your application is already logging caught exceptions in this manner, as it should be, then implementing will be a snap! The webapp framework, like many others, automatically logs uncaught exceptions, which will be included in the email report as well.

Using ereporter in your applications

In your handler script(s), add:

import logging
from google.appengine.ext import ereporter

ereporter.register_logger()

In your app.yaml, add:

handlers:
- url: /_ereporter.*
  script: $PYTHON_LIB/google/appengine/ext/ereporter/report_generator.py
  login: admin

In your cron.yaml, add:

cron:
- description: Daily exception report
  url: /_ereporter?sender=you@yourdomain.com  # The sender must be an app admin.
  schedule: every day 00:00

This will send an email report of all exceptions at midnight UTC everyday. Refer to the schedule format documentation to customize your cron.yaml further.

If you anticipate a lot of exception traces (for example, if you're deploying many minor versions, each of which may have its own set of exceptions), you can ensure that the traces from the newest minor versions get included by adding this to your index.yaml:

indexes:
- kind: ExceptionRecord
  properties:
  - name: date
  - name: major_version
  - name: minor_version
    direction: desc

Note: The google.appengine.ext.ereporter package uses the datastore to maintain logged exceptions. This will affect what is displayed in the Datastore Viewer, and the data exported using the Bulkloader.

Customizing your reports

Developers can customize exception email reports by using the following URL query string arguments in cron.yaml. Valid query string arguments include:

delete

Set to false to prevent deletion of exception records from the datastore after sending a report. Defaults to true.

debug

Set to true to return the report in the response instead of emailing it.

date

The date to generate the report for, in yyyy-mm-dd format. Defaults to yesterday's date. Useful for debugging.

max_results

Maximum number of entries to include in a report. The default is 100.

sender

The email address to use as the sender. Must be an active administrator.

to

If specified, send reports to this address. If not specified, all admins are sent the report.

versions

Set to all to report on all minor versions, or latest for the latest.

Customized report example

The following cron.yaml will send an exception report from only the latest deployed minor version at midnight UTC to all application developers without deleting the records from the datastore:

cron:
- description: Daily exception report
  url: /_ereporter?sender=you@yourdomain.com&versions=latest&delete=false
  schedule: every day 00:00

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.