README.md 8.8 KB
Newer Older
Miquel Torres's avatar
Miquel Torres committed
1
# Codespeed
2
[![Build Status](https://travis-ci.org/tobami/codespeed.png?branch=master)](https://travis-ci.org/tobami/codespeed)
Miquel Torres's avatar
Miquel Torres committed
3
[![PyPI version](https://img.shields.io/pypi/v/codespeed.svg)](https://pypi.python.org/pypi/codespeed)
Chris Adams's avatar
Chris Adams committed
4

5
Codespeed is a web application to monitor and analyze the performance of your code.
Miquel Torres's avatar
Miquel Torres committed
6

Alexey Palazhchenko's avatar
Alexey Palazhchenko committed
7
Known to be used by [CPython](https://speed.python.org), [PyPy](http://speed.pypy.org), [Twisted](http://speed.twistedmatrix.com) and others.
Miquel Torres's avatar
Tag 0.8    
Miquel Torres committed
8
9

For an overview of some application concepts see the [wiki page](https://github.com/tobami/codespeed/wiki/Overview)
10

Miquel Torres's avatar
Miquel Torres committed
11
# Installation
Chris Adams's avatar
Chris Adams committed
12

13
You will need Python 2.7 or 3.4+.
Miquel Torres's avatar
Tag 0.8    
Miquel Torres committed
14

Miquel Torres's avatar
Miquel Torres committed
15
To install dependencies and the codespeed Django app:
Miquel Torres's avatar
Tag 0.8    
Miquel Torres committed
16

Miquel Torres's avatar
Miquel Torres committed
17
    pip install codespeed
Chris Adams's avatar
Chris Adams committed
18

Miquel Torres's avatar
Miquel Torres committed
19
If you want version control integration, there are additional requirements:
Chris Adams's avatar
Chris Adams committed
20

21
22
23
* Subversion needs pysvn: `python-svn`
* Mercurial needs the package `mercurial` to clone the repo locally
* git needs the `git` package to clone the repo
Miquel Torres's avatar
Miquel Torres committed
24
25
26
27
* For Github the isodate package is required, but not git: `pip install isodate`

**Note**: For git or mercurial repos, the first time the changes view is accessed,
Codespeed will try to clone the repo, which depending on the size of the project
Stefan Marr's avatar
Stefan Marr committed
28
can take a long time. Please be patient.
Miquel Torres's avatar
Miquel Torres committed
29

Chris Adams's avatar
Chris Adams committed
30
* Download the last stable release from
31
  [github.com/tobami/codespeed/tags](https://github.com/tobami/codespeed/tags), unpack it and install it with `python setup.py install`.
32
* To get started, you can use the `sample_project` directory as a starting point for your Django project, which can be normally configured by editing `sample_project/settings.py`.
Chris Adams's avatar
Chris Adams committed
33
* For simplicity, you can use the default sqlite configuration, which will save
34
35
  the data to a database named `data.db`
* Create the DB by typing from the root directory:
Chris Adams's avatar
Chris Adams committed
36

Miquel Torres's avatar
Tag 0.8    
Miquel Torres committed
37
        python manage.py migrate
Chris Adams's avatar
Chris Adams committed
38

39
40
41
42
* Create an admin user:

        python manage.py createsuperuser

Chris Adams's avatar
Chris Adams committed
43
44
* For testing purposes, you can now start the development server:

Chris Adams's avatar
Chris Adams committed
45
        python manage.py runserver 8000
Chris Adams's avatar
Chris Adams committed
46

Miquel Torres's avatar
Miquel Torres committed
47
48
The codespeed installation can now be accessed by navigating to `http://localhost:8000/`.

49
**Note**: for production, you should configure a real server like Apache or nginx (refer to the [Django docs](http://docs.djangoproject.com/en/dev/howto/deployment/)). You should also
50
modify `sample_project/settings.py` and set `DEBUG = False`.
Miquel Torres's avatar
Miquel Torres committed
51
[`sample_project/README.md`](https://github.com/tobami/codespeed/tree/master/sample_project/README.md) also describes some production settings.
Miquel Torres's avatar
Miquel Torres committed
52
53

# Codespeed configuration
Chris Adams's avatar
Chris Adams committed
54

Miquel Torres's avatar
Miquel Torres committed
55
56
57
58
## Using the provided test data

If you want to test drive Codespeed, you can use the testdata.json fixtures to have a working data set to browse.

59
* From the root directory, type:
Miquel Torres's avatar
Miquel Torres committed
60

61
        ./manage.py loaddata codespeed/fixtures/testdata.json
Miquel Torres's avatar
Miquel Torres committed
62
63
64

## Starting from scratch

Chris Adams's avatar
Chris Adams committed
65
66
Before you can start saving (and displaying) data, you need to first create an
environment and define a default project.
67

Miquel Torres's avatar
Miquel Torres committed
68
* Go to `http://localhost:8000/admin/codespeed/environment/`
Chris Adams's avatar
Chris Adams committed
69
  and create an environment.
Miquel Torres's avatar
Miquel Torres committed
70
* Go to `http://localhost:8000/admin/codespeed/project/`
Chris Adams's avatar
Chris Adams committed
71
72
73
74
  and create a project.

Check the field "Track changes" and, in case you want version control
integration, configure the relevant fields.
Miquel Torres's avatar
Miquel Torres committed
75

Chris Adams's avatar
Chris Adams committed
76
77
**Note**: Only executables associated to projects with a checked "track changes"
field will be shown in the Changes and Timeline views.
Miquel Torres's avatar
Miquel Torres committed
78

79
**Note**: Git and Mercurial need to locally clone the repository. That means that your `sample_project/repos` directory will need to be owned by the server. In the case of a typical Apache installation, you'll need to type `sudo chown www-data:www-data sample_project/repos`
80

Miquel Torres's avatar
Miquel Torres committed
81
# Saving data
Chris Adams's avatar
Chris Adams committed
82

83
Data is saved POSTing to `http://localhost:8000/result/add/`.
Chris Adams's avatar
Chris Adams committed
84

Miquel Torres's avatar
Miquel Torres committed
85
You can use the script `tools/save_single_result.py` as a guide.
Miquel Torres's avatar
Miquel Torres committed
86
87
When saving large quantities of data, it is recommended to use the JSON API instead:
    `http://localhost:8000/result/add/json/`
Miquel Torres's avatar
Miquel Torres committed
88

Miquel Torres's avatar
Miquel Torres committed
89
90
91
An example script is located at `tools/save_multiple_results.py`

**Note**: If the given executable, benchmark, project, or
Chris Adams's avatar
Chris Adams committed
92
93
94
95
96
revision do not yet exist, they will be automatically created, together with the
actual result entry. The only model which won't be created automatically is the
environment. It must always exist or the data won't be saved (that is the reason
it is described as a necessary step in the previous "Codespeed configuration"
section).
Miquel Torres's avatar
Miquel Torres committed
97

Miquel Torres's avatar
Miquel Torres committed
98
99
# Further customization

Chris Adams's avatar
Chris Adams committed
100
101
## Custom Settings

102
103
You may override any of the default settings by setting them in
`sample_project/settings.py`. It is strongly recommended that you only override the
Chris Adams's avatar
Chris Adams committed
104
105
106
settings you need by importing the default settings and replacing only the
values needed for your customizations:

107
    from codespeed.settings import *
Chris Adams's avatar
Chris Adams committed
108

109
    DEF_ENVIRONMENT = "Dual Core 64 bits"
Chris Adams's avatar
Chris Adams committed
110
111
112

### Site-wide Changes

113
114
All pages inherit from the `base.html` template. To change every page on the site 
simply edit (`sample_project/templates/codespeed/base_site.html`) and override
Chris Adams's avatar
Chris Adams committed
115
116
117
118
119
the appropriate block:

* Custom title: you may replace the default "My Speed Center" for the title
  block with your prefered value:

120
        {% block title %}
Chris Adams's avatar
Chris Adams committed
121
122
123
            My Project's Speed Center
        {% endblock %}

124
125
126
* Replacing logo.png: Place your logo in `sample_project/static/images/logo.png`
* Logo with custom filename: Place your logo in `sample_project/static/images/` and add a block like
  this to `base_site.html`:
Chris Adams's avatar
Chris Adams committed
127
128

        {% block logo %}
129
            <img src="{{ MEDIA_URL }}images/my-logo.jpg" width="120" height="48" alt="My Project">
Chris Adams's avatar
Chris Adams committed
130
131
132
133
134
        {% endblock logo %}

  n.b. the layout will stay exactly the same for any image with a height of
  48px (any width will do)

135
* Custom JavaScript or CSS: add your files to the `sample_project/static/js` directory
Chris Adams's avatar
Chris Adams committed
136
137
138
139
  and extend the `extra_head` template block:

        {% block extra_head %}
            {{ block.super }}
140
            <script type="text/javascript" src="{{ MEDIA_URL }}static/js/my_cool_tweaks.js">
Chris Adams's avatar
Chris Adams committed
141
142
143
144
        {% endblock extra_head %}

### Specific Pages

145
Since `sample_project/templates/codespeed` is the first entry in `settings.TEMPLATE_DIRS` you
Chris Adams's avatar
Chris Adams committed
146
147
may override any template on the site simply by creating a new one with the
same name.
148

149
* About page: create `sample_project/templates/about.html`:
Chris Adams's avatar
Chris Adams committed
150

151
        {% extends "codespeed/base_site.html" %}
Chris Adams's avatar
Chris Adams committed
152
153
154
155
156
157
158
        {% block title %}{{ block.super }}: About this project{% endblock %}
        {% block body %}
            <div id="sidebar"></div>
            <div id="about" class="about_content clearfix">
                Your content here
            </div>
        {% endblock %}
Chris Adams's avatar
Chris Adams committed
159

Miquel Torres's avatar
Miquel Torres committed
160

Miquel Torres's avatar
Miquel Torres committed
161
## Baselines and Comparison view executables
Chris Adams's avatar
Chris Adams committed
162
163
164
165
* The results associated to an executable and a revision which has a non blank
  tag field will be listed as a baseline option in the Timeline view.
* Additionaly, the Comparison view will show the results of the latest revision
  of projects being tracked as an executable as well.
Miquel Torres's avatar
Miquel Torres committed
166

Miquel Torres's avatar
Miquel Torres committed
167
## Defaults
168
The file `sample_project/settings.py` can contain customizations of
Chris Adams's avatar
Chris Adams committed
169
several parameters (the file includes comments with full examples).
Miquel Torres's avatar
Miquel Torres committed
170

Miquel Torres's avatar
Miquel Torres committed
171
### General settings:
172
173
* `WEBSITE_NAME`: The RSS results feed will use this parameter as the site name
* `DEF_BASELINE`: Defines which baseline option will be chosen as default in
174
  the Timeline and Changes views.
175
* `DEF_ENVIRONMENT`: Defines which environment should be selected as default
176
  in the Changes and Timeline views.
177
178
* `CHANGE_THRESHOLD`
* `TREND_THRESHOLD`
179

Miquel Torres's avatar
Miquel Torres committed
180
### Changes View
181
* `DEF_EXECUTABLE`: in the Changes view, a random executable is chosen as
Chris Adams's avatar
Chris Adams committed
182
183
  default. It that doesn't suite you, you can specify here which one should be
  selected. You need to specify its id (since the name alone is not unique).
184

Miquel Torres's avatar
Miquel Torres committed
185
### Timeline View
186
* `DEF_BENCHMARK`: Defines the default timeline view. Possible values:
Miquel Torres's avatar
Miquel Torres committed
187
188
189
190
    * `None`: will show a grid of plot thumbnails, or a text message when the number of plots exceeds 30
    * `grid`: will always show as default the grid of plots
    * `show_none`: will show a text message (better default when there are lots of benchmarks)
    * `mybench`: will select benchmark named "mybench"
191

Miquel Torres's avatar
Miquel Torres committed
192
### Comparison View
193
* `CHART_TYPE`: Chooses the default chart type (normal bars, stacked bars or
Chris Adams's avatar
Chris Adams committed
194
  relative bars)
195
* `NORMALIZATION`: Defines whether normalization should be enabled as default
196
  in the Comparison view.
197
198
* `CHART_ORIENTATION`: horizontal or vertical
* `COMP_EXECUTABLES`: per default all executables will be checked. When there
199
200
  are a large number of tags or executables, it is better to only select a few
  so that the plots are not too cluttered.
201
  Given as a list of tuples containing the name of an executable + commitid of a revision. An 'L' denotes the last revision. Example:
Miquel Torres's avatar
Miquel Torres committed
202

203
```python
Miquel Torres's avatar
Miquel Torres committed
204
205
COMP_EXECUTABLES = [
    ('myexe', '21df2423ra'),
Miquel Torres's avatar
Miquel Torres committed
206
207
    ('myexe', 'L'),
]
208
```
209
210

## Getting help
211
212
213
For help regarding the configuration of Codespeed, or to share any ideas or
suggestions you may have, please post on Codespeed's [discussion
group](http://groups.google.com/group/codespeed)
214
215
216

## Reporting bugs

217
218
If you find any bug in Codespeed please report it on the
[Github issue tracker](https://github.com/tobami/codespeed/issues)