Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 161 lines (106 sloc) 4.23 kb
5d1c29b @colinhowe Django SQL Sampler -> Django Sampler
colinhowe authored
1 ==============
2 Django Sampler
3 ==============
d203b9a @colinhowe Initial commit!
colinhowe authored
4
5 Author: Colin Howe (@colinhowe)
21ea4c6 @colinhowe Tweak README
colinhowe authored
6
d203b9a @colinhowe Initial commit!
colinhowe authored
7 License: Apache 2.0
8
9 About
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
10 =====
d203b9a @colinhowe Initial commit!
colinhowe authored
11
5d1c29b @colinhowe Django SQL Sampler -> Django Sampler
colinhowe authored
12 Django Sampler allows you to sample a percentage of your queries (SQL, Mongo,
13 etc) and view the ones that are taking up the most time. The queries are grouped
d203b9a @colinhowe Initial commit!
colinhowe authored
14 together by where they originated from in your code.
15
16 Installation
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
17 ============
d203b9a @colinhowe Initial commit!
colinhowe authored
18
19 Install::
21ea4c6 @colinhowe Tweak README
colinhowe authored
20
d203b9a @colinhowe Initial commit!
colinhowe authored
21 python setup.py install
22
23 Configure:
5d1c29b @colinhowe Django SQL Sampler -> Django Sampler
colinhowe authored
24 * Add djangosampler to your INSTALLED_APPS
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
25 * Add the tables (manage.py syncdb or manage.py migrate if you use South)
d203b9a @colinhowe Initial commit!
colinhowe authored
26 * Add the views::
21ea4c6 @colinhowe Tweak README
colinhowe authored
27
d203b9a @colinhowe Initial commit!
colinhowe authored
28 urlpatterns += patterns('',
5d1c29b @colinhowe Django SQL Sampler -> Django Sampler
colinhowe authored
29 (r'^sampler/', include('djangosampler.urls')),
d203b9a @colinhowe Initial commit!
colinhowe authored
30 )
3b45f6e @colinhowe Fix README
colinhowe authored
31
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
32 * Set DJANGO_SAMPLER_FREQ to a value other than 0
33 * Set DJANGO_SAMPLER_PLUGINS to a list of plugins. For just sampling SQL a
34 sensible default is::
35
36 DJANGO_SAMPLER_PLUGINS = (
37 'djangosampler.plugins.sql.Sql',
38 # Plugins are applied in the same order as this list
39 )
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
40
caa84ea @colinhowe Edited README.rst via GitHub
colinhowe authored
41 There are several plugins available and it is worthwhile reading through
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
42 them to get the most use out of this tool.
b7a936f @colinhowe Improve bias and cost calculations to better allow for small frequent qu...
colinhowe authored
43 * If you are using cost based sampling then set DJANGO_SAMPLER_BASE_TIME to
44 the expected duration of a normal query in seconds. By default this is set
45 to 5ms.
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
46
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
47
3b45f6e @colinhowe Fix README
colinhowe authored
48 Viewing Results
49 ===============
50
51 After letting the sampler run for a while you will be able to view queries
52 (grouped by their origin) at the URL you configured.
53
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
54 Configuration
55 =============
56
57 DJANGO_SAMPLER_PLUGINS
58 ~~~~~~~~~~~~~~~~~~~~~~
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
59
5d1c29b @colinhowe Django SQL Sampler -> Django Sampler
colinhowe authored
60 Django Sampler has a plugin architecture to allow you to control how
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
61 much data you want to be collected.
62
63 In your settings.py add the following::
64
65 DJANGO_SAMPLER_PLUGINS = (
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
66 'djangosampler.plugins.sql.Sql',
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
67 # Plugins are applied in the same order as this list
68 )
d203b9a @colinhowe Initial commit!
colinhowe authored
69
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
70 The example above will add the SQL plugin.
71
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
72 Available plugins and their settings are described in the Plugins section below.
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
73
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
74 DJANGO_SAMPLER_FREQ
75 ~~~~~~~~~~~~~~~~~~~
d203b9a @colinhowe Initial commit!
colinhowe authored
76
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
77 DJANGO_SAMPLER_FREQ configures the percentage of queries that will be recorded.
78 It should be between 0.0 and 1.0.
d203b9a @colinhowe Initial commit!
colinhowe authored
79
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
80 If this is not set then no plugins will be installed and your code will run as
81 normal.
d203b9a @colinhowe Initial commit!
colinhowe authored
82
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
83 DJANGO_SAMPLER_USE_COST
84 ~~~~~~~~~~~~~~~~~~~~~~~
f37e2af @colinhowe Clarification in README
colinhowe authored
85
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
86 DJANGO_SAMPLER_USE_COST will enable cost-based sampling. This causes queries
87 that run for a long time to be sampled more often than short queries.
d203b9a @colinhowe Initial commit!
colinhowe authored
88
89 The chance that a query is sampled is multiplied by the total time the query
90 takes. If a query takes 2 seconds then it will be twice as likely to be sampled
91 as a query that takes 1 second.
92
93 The cost for a query is adjusted to account for this as follows::
21ea4c6 @colinhowe Tweak README
colinhowe authored
94
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
95 cost = max(1.0, time * DJANGO_SAMPLER_FREQ) / DJANGO_SAMPLER_FREQ
96
97 Plugins
98 =======
99
3b45f6e @colinhowe Fix README
colinhowe authored
100 A list of available plugins follows. You can write your own plugin and this is
101 described in the section 'Writing Your Own Plugins'.
102
103 Django SQL
104 ~~~~~~~~~~
e56d2b3 @colinhowe Move SQL sampler over towards new plugin architecture
colinhowe authored
105
106 Plugin class: djangosampler.plugins.sql.Sql
107
108 The SQL sampler plugin will sample a percentage of SQL queries that occur in
109 your application. The samples will be grouped by query and stack traces will be
110 recorded to find where the queries are originating.
d203b9a @colinhowe Initial commit!
colinhowe authored
111
c70339a @colinhowe Update README and fix view name in wrapped views
colinhowe authored
112 Django Requests
113 ~~~~~~~~~~~~~~~
114
115 Plugin class: djangosampler.plugins.request.Request
116
117 The request plugin installs a Middleware that will sample the time taken by
118 requests.
119
e8338ed @colinhowe Add context manager for sampling any code
colinhowe authored
120 Sample any code
121 ~~~~~~~~~~~~~~~
122
123 This is not strictly a plugin. This is a context manager that will allow you
124 to mark blocks of code and sample how long the blocks take to run. E.g.::
125
126 from djangosampler.sampler import sampling
127
128 with sampling('my_code', 'some_fn'):
129 do_something_slow()
130
c70339a @colinhowe Update README and fix view name in wrapped views
colinhowe authored
131 Celery
132 ~~~~~~
133
134 Plugin class: djangosampler.plugins.celery_task.Celery
135
136 The Celery plugin uses Celery's signals to sample the time taken to execute
137 tasks.
138
e01cb9f @colinhowe Add MongoDB to readme
colinhowe authored
139 MongoDB
140 ~~~~~~~
141
142 Plugin class: djangosampler.plugins.mongo.Mongo
143
144 The MongoDB plugin will sample a percentage of Mongo commands (queries,
145 inserts, etc) that occur in your application. The samples will be grouped by
146 command and stack traces will be recorded to find where the queries are
147 originating.
148
149
3b45f6e @colinhowe Fix README
colinhowe authored
150 Writing Your Own Plugins
151 ========================
d203b9a @colinhowe Initial commit!
colinhowe authored
152
3b45f6e @colinhowe Fix README
colinhowe authored
153 TODO. For now, look in the plugins folder and copy :)
8b6b072 @colinhowe Edited README.rst via GitHub
colinhowe authored
154
d203b9a @colinhowe Initial commit!
colinhowe authored
155 Feedback
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
156 ========
d203b9a @colinhowe Initial commit!
colinhowe authored
157
ebfa389 @colinhowe Update README to reflect desired behaviour
colinhowe authored
158 Feedback is always welcome! Github or twitter (@colinhowe) are the best places
159 to reach me.
3b45f6e @colinhowe Fix README
colinhowe authored
160
Something went wrong with that request. Please try again.