Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 170 lines (110 sloc) 4.17 kb
d617116 @jedp added travis-ci hook
authored
1 [![build status](https://secure.travis-ci.org/jedp/kpiggybank.png)](http://travis-ci.org/jedp/kpiggybank)
ed08b4c @jedp initial commit; just getting started
authored
2 KPIggyBank
3 ==========
4
49277f8 @jedp added usage documentation
authored
5 A backend store for Key Performance Indicator (KPI) data.
ed08b4c @jedp initial commit; just getting started
authored
6
49277f8 @jedp added usage documentation
authored
7 Node.JS + CouchDB.
ed08b4c @jedp initial commit; just getting started
authored
8
49277f8 @jedp added usage documentation
authored
9 Requirements
10 ------------
ed08b4c @jedp initial commit; just getting started
authored
11
f7c5030 @jedp updated docs for database backends
authored
12 - An accessible CouchDB server for persistence.
49277f8 @jedp added usage documentation
authored
13 - Node.JS (0.6.17 or greater)
ed08b4c @jedp initial commit; just getting started
authored
14
49277f8 @jedp added usage documentation
authored
15 Installation
16 ------------
ed08b4c @jedp initial commit; just getting started
authored
17
49277f8 @jedp added usage documentation
authored
18 - git clone: `https://github.com/jedp/kpiggybank`
19 - `npm install`
ed08b4c @jedp initial commit; just getting started
authored
20
49277f8 @jedp added usage documentation
authored
21 Testing
22 -------
ed08b4c @jedp initial commit; just getting started
authored
23
49277f8 @jedp added usage documentation
authored
24 - `npm test`
ed08b4c @jedp initial commit; just getting started
authored
25
49277f8 @jedp added usage documentation
authored
26 The test suite simulates throwing a thousand login sequences at the KPI store.
ed08b4c @jedp initial commit; just getting started
authored
27
49277f8 @jedp added usage documentation
authored
28 It is anticipated that, with 1 million users, BrowserID will generate some
29 100 sign-in activities per second. The test suite requires that kpiggy bank
30 can completely store and retrieve records at a rate at least twice as fast
31 as this.
ed08b4c @jedp initial commit; just getting started
authored
32
f7c5030 @jedp updated docs for database backends
authored
33 If you want to experiment with the server without having couch installed,
34 use the in-memory data store:
35
36 DB_BACKEND=memory node lib/server.js
37
38 Note that the in-memory data is not saved anywhere. It's just for testing.
39
49277f8 @jedp added usage documentation
authored
40 Running
41 -------
42
43 For configuration, the file `env.sh.dist` can be copied to `env.sh` and edited.
44 kpiggybank will look for the following environment variables:
45
f7c5030 @jedp updated docs for database backends
authored
46 - `DB_BACKEND`: One of "couchdb", "memory", "dummy". Default "couchdb".
47 - `DB_HOST`: IP addr of couch server. Default "127.0.0.1".
48 - `DB_PORT`: Port number of couch server. Default "5984".
49 - `DB_NAME`: Name of the database. Default "bid_kpi".
50 - `DB_USER`: Username for database if required. Default "kpiggybank".
51 - `DB_PASS`: Password for database if required. Default "kpiggybank".
554a83b @jedp fits better with awsbox env now
authored
52 - `HOST`: "127.0.0.1"
53 - `PORT`: Port for the kpiggybank server. Default "3000".
54 - `MODE`: Governs how verbose logging should be. Set to "prod" for quieter logging. Default "dev".
49277f8 @jedp added usage documentation
authored
55
9d782ef @jedp formatting tweaks
authored
56 Start the server like so:
57
49277f8 @jedp added usage documentation
authored
58 - `npm start`
59
9d782ef @jedp formatting tweaks
authored
60
61 Or like so:
62
63 - `node lib/server.js`
64
49277f8 @jedp added usage documentation
authored
65 Or change your env configuration with something like:
66
f7c5030 @jedp updated docs for database backends
authored
67 - `DB_NAME=bid_kpi_test npm start`
49277f8 @jedp added usage documentation
authored
68
69 When running kpiggybank for the first time on a given database, it will
70 ensure that the db exists, creating it if it doesn't.
71
72 Please note that the database named `bid_kpi_test` is **deleted** as part of the
73 test suite.
74
75
76 JS API
77 ------
78
f717aec @jedp fixed documentation formatting
authored
79 ### Methods
80
81 - `api.saveData(blob [, callback])` - save a hopefully valid event blob
82 - `api.fetchRange([ options, ] callback)` - fetch some or all events
83 - `api.count(callback)` - get number of records in DB
84 - `api.followChanges()` - connect to event stream
85
86 ### Events
87
88 - `change` - a newly-arrived json blob of delicious KPI data
89 - `error` - oh noes
90
91 ### Examples
92
49277f8 @jedp added usage documentation
authored
93 The HTTP API calls are wrapped for convenience in a JS module. You can of
94 course call the HTTP methods directly if you want. Example of using the JS
95 API:
96
f717aec @jedp fixed documentation formatting
authored
97 ``` js
49277f8 @jedp added usage documentation
authored
98 var API = require("lib/api");
99 var api = new API(server_host, server_port);
100 api.saveData(yourblob, yourcallback);
f717aec @jedp fixed documentation formatting
authored
101 ```
49277f8 @jedp added usage documentation
authored
102
103 The callback is optional.
104
4ae25bc @jedp documented fetchRange api
authored
105 To query a range:
106
f717aec @jedp fixed documentation formatting
authored
107 ``` js
f12fd7e @jedp refactored GET methods in api; updated tests and docs
authored
108 var options = {start: 1, end: 42}; // optional
109 api.fetchRange(options, callback);
f717aec @jedp fixed documentation formatting
authored
110 ```
4ae25bc @jedp documented fetchRange api
authored
111
f12fd7e @jedp refactored GET methods in api; updated tests and docs
authored
112 options are ... optional, so you can get all records like so:
4ae25bc @jedp documented fetchRange api
authored
113
f717aec @jedp fixed documentation formatting
authored
114 ``` js
f12fd7e @jedp refactored GET methods in api; updated tests and docs
authored
115 api.fetchRange(callback);
f717aec @jedp fixed documentation formatting
authored
116 ```
117
118 Subscribe to changes stream. The changes stream is an event emitter. Use like
119 so:
120
121 ``` js
122 api.followChanges() // now subscribed
d0383d7 @jedp added a count query
authored
123
f717aec @jedp fixed documentation formatting
authored
124 api.on('change', function(change) {
125 // do something visually stunning
126 });
127 ```
d0383d7 @jedp added a count query
authored
128
4ae25bc @jedp documented fetchRange api
authored
129
49277f8 @jedp added usage documentation
authored
130 HTTP API
131 --------
132
133 *Post Data*
134
135 Post a blob of data to `/wsapi/interaction_data`.
136 The post `data` should contain a JSON object following
9d782ef @jedp formatting tweaks
authored
137 the example here:
138 https://wiki.mozilla.org/Privacy/Reviews/KPI_Backend#Example_data
49277f8 @jedp added usage documentation
authored
139
140 In particular, the `timestamp` field is required, and should be a unix
141 timestamp (seconds since the epoch); not an ISO date string.
142
3d8b16f @jedp Oh? Is this markdown? Not rst? ...
authored
143 - url: `/wsapi/interaction_data`
144 - method: POST
145 - required param: `{data: <your data blob>}`
49277f8 @jedp added usage documentation
authored
146
147 *Get Data*
148
4ae25bc @jedp documented fetchRange api
authored
149 Retrieve a range of records; returns a JSON string.
49277f8 @jedp added usage documentation
authored
150
4ae25bc @jedp documented fetchRange api
authored
151 - url: `/wsapi/interaction_data?start=<date-start>&end=<date-end>`
3d8b16f @jedp Oh? Is this markdown? Not rst? ...
authored
152 - method: GET
ed08b4c @jedp initial commit; just getting started
authored
153
d0383d7 @jedp added a count query
authored
154 *Count Records*
ed08b4c @jedp initial commit; just getting started
authored
155
d0383d7 @jedp added a count query
authored
156 Retrieve a count of the number of records; returns a JSON encoded number.
157
158 - url: `/wsapi/interaction_data/count`
159 - method: GET
755c03d @jedp added license
authored
160
161 License
162 -------
163
164 All source code here is available under the [MPL 2.0][] license, unless
165 otherwise indicated.
166
167 [MPL 2.0]: https://mozilla.org/MPL/2.0/
168
169
Something went wrong with that request. Please try again.