Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
The Python SDK includes the Appstats library used for profiling the RPC (Remote Procedure Call) performance of your application. An App Engine RPC is a roundtrip network call between your application and an App Engine Service API. For example, all of these API calls are RPC calls:
db.get()
, db.put()
,
or db.query()
.
memcache.get()
, or memcache.get_multi()
.
urlfetch.fetch()
.
mail.send()
.
Optimizing or debugging performance of a scalable application can be a challenge because numerous issues can cause poor performance. These issues are very difficult to debug with the usual sources of information, like logs or request time stats. Most application requests spend the majority of their time waiting for network calls to complete as part of satisfying the request.
To keep your application fast, you need to know:
The Appstats library helps you answer these questions and verify that your application is using RPC calls in the most efficient way by allowing you to profile your RPC calls. Appstats allows you to trace all RPC calls for a given request and reports on the time consumed by each call.
Optimizing your application's RPC usage may also reduce your bill. See the Managing Your App's Resource Usage article.
There is nothing to download or install to begin using Appstats. You just need to configure your application, redeploy, and access the Appstats console as described in the steps below. The Appstats library takes care of the rest.
To record statistics about web requests, each request handler for your application must invoke Appstats. Depending on the framework used by your application, choose one of the following:
WSGI-compatible framework
To use Appstats with a WSGI-compatible framework (such as
webapp),
you must use the
run_wsgi_app()
function to invoke the application in your request handler scripts.
If you use another method to invoke a WSGI application
(such as wsgiref.handlers.CGIHandler
),
you must modify all of your handlers to use run_wsgi_app()
.
If it does not already exist, create a file named
appengine_config.py
in your application's root directory.
Add the following function to the file:
def webapp_add_wsgi_middleware(app): from google.appengine.ext.appstats import recording app = recording.appstats_wsgi_middleware(app) return app
The run_wsgi_app()
function imports this file and calls the
webapp_add_wsgi_middleware(app)
function, if found.
See Optional Configuration
below for more information on appengine_config.py
.
Django framework
To install the Appstats middleware in a Django application,
edit your settings.py
file,
and add the following line to be the first item in
MIDDLEWARE_CLASSES
:
MIDDLEWARE_CLASSES = ( 'google.appengine.ext.appstats.recording.AppStatsDjangoMiddleware', # ... )
The Appstats middleware must be the first item, so the profiler can include other middleware in its statistics.
The Django middleware calls Appstats to record events, as appropriate. You do not need to change any other application code.
The Appstats console is accessed by visiting a URL for your application in a web browser. You must set the path of the URL in one of two ways:
Default URL
To map Appstats to the default directory (/_ah/stats/
),
add the appstats
builtin to your app.yaml
file:
builtins: - appstats: on
Custom URL
If you need to map Appstats to a directory other than the default,
you can use the url
directive in app.yaml
:
- url: /stats.* script: $PYTHON_LIB/google/appengine/ext/appstats/ui.py
Tip:
By default, the Appstats console can only be accessed by application administrators.
The handler does not need to be restricted in configuration with login:
admin
.
You can configure the behavior of Appstats by adding content to the
appengine_config.py
file in your application's root directory.
For a complete example of configuration options,
see the file
google/appengine/ext/appstats/sample_appengine_config.py
in the SDK.
Some things to know about appengine_config.py
:
sys.path
,
you must make the same modifications to
sys.path
in appengine_config.py
so the Appstats web interface can see all files.
run_wsgi_app()
to invoke Django
(instead of using the middleware method described above)
and you call google.appengine.dist.use_library()
to select a Django version,
you must also add this call to appengine_config.py
.
(We recommend using the middleware method instead.)
You can test your Appstats setup with the development server. If you configured the console path to use the default URL above, you can access the console at http://localhost:8080/_ah/stats/.
Once you are satisfied with your Appstats setup, deploy your application.
If you configured the console path to use the default URL above,
you can access the console at
http://your_app_id.appspot.com/_ah/stats
.
The Appstats Console provides high-level information on RPC calls made, URL paths requested, a history of recent requests, and details of individual requests:
Appstats uses API hooks to add itself to the remote procedure call framework that underlies the App Engine service APIs. It records statistics for all API calls made during the request handler, then stores the data in memcache, using a namespace of __appstats__
. Appstats retains statistics for the most recent 1,000 requests. The data includes summary records, about 200 bytes each, and detail records, which can be up to 100 KB each. You can control the amount of detail stored in detail records. (See Optional Configuration and the example configuration file.)
The API hooks add some overhead to the request handlers. Appstats adds a message to the logs at the "info" level to report the amount of resources consumed by the Appstats library itself. The log line looks something like this:
INFO 2009-08-25 12:04:07,277 recording.py:290] Saved; key: __appstats__:046800, part: 160 bytes, full: 25278 bytes, overhead: 0.019 + 0.018; link: http://your_app_id.appspot.com/stats/detail?time=1234567890123
This line reports the memcache key that was updated, the size of the summary (part
) and detail (full
) records, and the time (in seconds) spent recording this information. The log line includes the link to the Appstats administrative interface that displays the data for this event.
Tip: Because Appstats hooks directly into the remote procedure call framework, the administrative interface may use API names that differ from the Python API your application uses. Most of these names are intuitive: for instance, datastore_v3.Get
is called by db.get()
or db.Model.get()
. Datastore queries usually involve a datastore_v3.RunQuery
followed by zero or more datastore_v3.Next
calls. (RunQuery
returns the first few results, so the API only uses Next
when fetching many results. Avoiding unnecessary Next
calls may speed up your app!)