Do not display branches that have been merged into master
[gipeda.git] / README.md
1 Gipeda -- the Git Performance Dashboard
2 =======================================
3
4 What is gipeda?
5 ---------------
6
7 Gipeda is a a tool that presents data from your program’s benchmark suite (or
8 any other source), with nice tables and shiny graphs.
9
10
11 It is only a frontend and does not help with or care about collecting the data.
12 So it is up to you whether you have a polling shell script loop, a post-commit
13 hook or a elaborate jenkins setup. As long as the performance data ends up in
14 the `logs/` directory, gipeda is happy.
15
16 Gipeda produces static pages. In fact, the (single) html file and the
17 accompagning JavaScript code is completely static. Giepda just generates a
18 large number of json files. This has the advantage of easy deployment: Just put
19 gipeda in your webspace of copy the files to some static web hosting and you
20 are done. This putts very little load on your server, is cache friendly and has
21 no security problems.
22
23 Do you want to see it live? Check out these:
24
25  * [Demo page], visualizing fairly boring stuff about gipeda itself.
26  * [GHC’s gipeda installation].
27
28 [Demo page]: http://perf.haskell.org/gipeda
29 [GHC’s gipeda installation]: https://perf.haskell.org/ghc
30
31 Setting it up
32 -------------
33
34  * Clone gipeda somewhere, possibly directly into your webspace.
35  * Install a Haskell compiler, including the `cablal` tool.
36  * Install a few packages
37
38         apt-get install git unzip libfile-slurp-perl libipc-run-perl
39
40  * Install the dependencies:
41
42         cabal install --only-dependencies
43
44  * Compile it:
45
46         cabal install --bindir=.
47
48  * Create a `settings.yaml`. You can look at the example file.
49  * Clone the repository of your project into `repository/`. A bare clone is
50    sufficient, e.g.
51
52         git clone  --bare git://git.haskell.org/ghc.git repository
53
54  * Download a bunch of JavaScript libraries by runing `./install-jslibs.sh`.    
55
56 Gipeda does not work without at least some logs, so lets add them.
57
58 Adding data
59 -----------
60
61 Gipeda expect simple CSV files for each revision, of the form
62
63     benchmark1;1000
64     benchmark2;20.123
65     benchmark3;0
66
67 But likely your benchmark suite does not generate them in this format directly.
68 Hence, put whatever format you have (text base logs, JUnit reports, whatever)
69 into the directory `logs`, named `<gitrev>.log`, e.g.
70 `logs/0279a7d327a3b962ffa93a95d47ea5d9ee31e25c.log`.
71
72 Then create a script `log2csv` that expects the filename of such a log on on
73 the command line and produces the desired CSV file.
74
75 Running gipeda
76 --------------
77
78 With everything in place, you can now run
79
80     ./gipeda
81
82 and it will create a bunch of JSON files in `site/out/`.  With `./gipda -j4`
83 you can parallize it.
84
85 You should do this everytime a new log file appears in `logs/`. You should also
86 make sure your repository is up-to-date, e.g. by running `git -C repository
87 pull` or, if it is a bare clone, `git -C repository fetch origin
88 "+refs/heads/*:refs/heads/*" --prune`.
89
90 Using gipeda
91 -------------
92
93 Finally, you simply point your browser to the `site/index.html`. The page
94 should be mostly self-explanatory. If you don’t see anything, it might be
95 because of the filter in the top-right corner. Try to enable all buttons, even
96 the `=`.
97
98 To host this on a webserver, just put the `site/` directory in your webspace.
99
100 Hacking on gipeda
101 -----------------
102
103 Gipeda doesn't do much; it mostly assembles the data and creates nice reports.
104 The rough pipeline is as follows:
105
106  * Directory `logs/` contains project-specific data per git commit that has
107    been benchmarked. gipeda will run `log2csv` on these files to generate the
108    files in `site/out/results`. `logs` may be a normal directory, or (for disk
109    space efficiency) a bare git repository. This step is optional.
110  * Directory `site/out/results` contains one csv file per git commit. The
111    format is simple, as there are two columns: benchmark name and a numerical
112    value.
113  * From these files, gipeda generates a number of JSON files, some per commit
114    (`report`, `summaries`), some global (`settings`, `latest-summaries`).
115
116    A crucial idea here is that these JSON files are all but fragments of a
117    theoretical global JSON document. In other words: You could combine them
118    (using a naive JSON object merge) and there would be no conflicts, and the
119    result could be used by the client as well.
120  * The client (`site/index.html` and `site/js/gipeda.js`) is a fairly standard
121    HTML+JS application using jquery, bootstrap, handlebars.
122
123 Bugs, Code, Contact
124 -------------------
125
126 Please reports bugs and missing features at the [GitHub bugtracker]. This is
127 also where you can find the [source code].
128
129 Gipeda was written by [Joachim Breitner] and is licensed under a permissive MIT
130 [license].
131
132 [GitHub bugtracker]: https://github.com/nomeata/gipeda/issues
133 [source code]: https://github.com/nomeata/gipeda
134 [Joachim Breitner]: http://www.joachim-breitner.de/
135 [license]: https://github.com/nomeata/gipeda/blob/LICENSE