Skip to content
Newer
Older
100644 142 lines (99 sloc) 3.49 KB
434c287 @schmichael Move links to top of README so they're on PyPI too
authored Mar 10, 2012
1 `Documentation <http://mmstats.readthedocs.org/>`_ |
2 `Package <http://pypi.python.org/pypi/mmstats>`_ |
3 `Code <http://github.com/schmichael/mmstats/>`_
4
d06c6af @schmichael Boring is better
authored Oct 4, 2011
5 =====
6 About
7 =====
01c6bb6 @schmichael Hey it's a readme!
authored Aug 15, 2011
8
1b424db @schmichael Update docs a bit
authored Jan 17, 2012
9 Mmstats is a way to expose and read diagnostic values and metrics for
10 applications.
01c6bb6 @schmichael Hey it's a readme!
authored Aug 15, 2011
11
18d370a @schmichael Cleanup flask example and associated docs
authored Nov 20, 2011
12 Think of mmstats as /proc for your application and the readers as procps
13 utilities.
29f974e @schmichael Compare my half baked barely working lib to venerable unix tools
authored Aug 15, 2011
14
1b424db @schmichael Update docs a bit
authored Jan 18, 2012
15 This project is a Python implementation, but compatible implementations can be
16 made in any language (see Goals).
17
432f5bd @schmichael Add link to mailing list
authored Mar 6, 2012
18 Discuss at https://groups.google.com/group/python-introspection
19
01c6bb6 @schmichael Hey it's a readme!
authored Aug 15, 2011
20 -----
21 Goals
22 -----
23
29f974e @schmichael Compare my half baked barely working lib to venerable unix tools
authored Aug 15, 2011
24 * Separate publishing/writing from consuming/reading tools
01c6bb6 @schmichael Hey it's a readme!
authored Aug 15, 2011
25 * Platform/language independent (a Java writer can be read by a Python tool)
26 * Predictable performance impact for writers via:
7bdb31b @schmichael I suck at rst
authored Aug 15, 2011
27
28 * No locks (1 writer per thread)
18d370a @schmichael Cleanup flask example and associated docs
authored Nov 20, 2011
29 * No syscalls (after instantiation)
7bdb31b @schmichael I suck at rst
authored Aug 15, 2011
30 * All in userspace
31 * Reading has no impact on writers
32
01c6bb6 @schmichael Hey it's a readme!
authored Aug 15, 2011
33 * Optional persistent (writer can sync anytime)
34 * 1-way (Publish/consume only; mmstats are not management extensions)
35
36 =====
37 Usage
38 =====
39
e795b06 @schmichael Can't resize mmap after initializing ctypes; determine total size first
authored Sep 10, 2011
40 ------------
41 Requirements
42 ------------
43
44 CPython 2.6 or 2.7 (Windows is untested)
45
eaa6688 @schmichael Update README to reflect pypy support
authored Nov 28, 2011
46 PyPy (only tested in 1.7, should be faster in 1.8)
e795b06 @schmichael Can't resize mmap after initializing ctypes; determine total size first
authored Sep 10, 2011
47
ad62d11 @schmichael Add setup.py and add usage notes to readme
authored Aug 19, 2011
48 -----
49 Using
50 -----
51
8e776a0 @schmichael Stop recommending users bundle mmstats.py
authored Jan 31, 2012
52 1. ``python setup.py install``
ad62d11 @schmichael Add setup.py and add usage notes to readme
authored Aug 19, 2011
53 2. ``import mmstats``
54 3. Create a subclass of mmstats.MmStats like:
55
56 ::
57
58 class WebStats(mmstats.MmStats):
1b424db @schmichael Update docs a bit
authored Jan 18, 2012
59 status2xx = mmstats.CounterField(label='status.2XX')
60 status3xx = mmstats.CounterField(label='status.3XX')
61 status4xx = mmstats.CounterField(label='status.4XX')
62 status5xx = mmstats.CounterField(label='status.5XX')
63 last_hit = mmstats.DoubleField(label='timers.last_hit')
ad62d11 @schmichael Add setup.py and add usage notes to readme
authored Aug 19, 2011
64
65 4. Instantiate it once per thread/process:
66
67 ::
68
69 webstats = WebStats(label_prefix='web.stats.')
70
71 5. Record some data:
72
73 ::
74
75 if response.status_code == 200:
1b424db @schmichael Update docs a bit
authored Jan 18, 2012
76 webstats.status2xx.inc()
77
78 webstats.last_hit = time.time()
ad62d11 @schmichael Add setup.py and add usage notes to readme
authored Aug 19, 2011
79
18d370a @schmichael Cleanup flask example and associated docs
authored Nov 20, 2011
80 6. Run ``slurpstats`` to read it
81 7. Run ``mmash`` to create a web interface for stats
82 8. Run ``pollstats -p web.stats.status 2XX,3XX,4XX,5XX /tmp/mmstats-*`` for a
83 vmstat/dstat like view.
5477c1b @schmichael Mention cleanstats in the readme
authored Jan 17, 2012
84 9. Did a process die unexpectedly and leave around a stale mmstat file?
85 ``cleanstats /path/to/mmstat/files`` will check to see which files are stale
86 and remove them.
ad62d11 @schmichael Add setup.py and add usage notes to readme
authored Aug 19, 2011
87
dfb7dfe @schmichael Add basic development instructions
authored Nov 9, 2011
88 -----------
89 Development
90 -----------
91
37881c4 @schmichael Add Travis-CI image and link
authored Mar 8, 2012
92 .. image:: https://secure.travis-ci.org/schmichael/mmstats.png?branch=master
93 :target: http://travis-ci.org/schmichael/mmstats/
94
dfb7dfe @schmichael Add basic development instructions
authored Nov 10, 2011
95 It's easiest to develop mmstats within a virtualenv:
96
43a7553 @schmichael Fix the dev instructions
authored Nov 9, 2011
97 ::
98
99 $ git clone git://github.com/schmichael/mmstats.git
100 $ cd mmstats
101 $ virtualenv .
102 $ source bin/activate
103 $ python setup.py develop
104 $ ./run_flask_example # This starts up a sample web app
623e97d @schmichael Flesh out the development example a bit more
authored Nov 9, 2011
105 $ curl http://localhost:5001/
106 $ curl http://localhost:5001/500
107 $ curl http://localhost:5001/status
108 $ # If you have ab installed:
109 $ ab -n 50 -c 10 http://localhost:5001/
110
111 Now to view the stats run the following in a new terminal:
112
113 ::
114
115 $ # To get a raw view of the data:
18d370a @schmichael Cleanup flask example and associated docs
authored Nov 20, 2011
116 $ slurpstats mmstats-*
43a7553 @schmichael Fix the dev instructions
authored Nov 10, 2011
117 $ # Or start up the web interface:
623e97d @schmichael Flesh out the development example a bit more
authored Nov 10, 2011
118 $ mmash
18d370a @schmichael Cleanup flask example and associated docs
authored Nov 20, 2011
119 $ # Run pollstats while ab is running:
120 $ pollstats -p flask.example. ok,bad,working mmstats-*
dfb7dfe @schmichael Add basic development instructions
authored Nov 10, 2011
121
18d370a @schmichael Cleanup flask example and associated docs
authored Nov 20, 2011
122 To cleanup stray mmstats files: ``rm mmstats-flask-*``
e5c9385 @schmichael Add cleanup command to docs
authored Nov 9, 2011
123
dfb7dfe @schmichael Add basic development instructions
authored Nov 10, 2011
124 The web interface will automatically reload when you change source files.
125
126 Put static files into static/ and template files into templates/
127
128 TODO: Factor mmash out into it's own project (with a meaningful name?)
129
130 --------
131 Testing
132 --------
01c6bb6 @schmichael Hey it's a readme!
authored Aug 15, 2011
133
5ba4d18 @schmichael Document easier to run test suite
authored Feb 16, 2012
134 Feel free to use your favorite test runner like `nose
135 <http://readthedocs.org/docs/nose/>`_ or `pytest <http://pytest.org/>`_ or just
136 run:
137
138 ::
139
140 $ python setup.py test
309684e @schmichael rst is hard
authored Aug 15, 2011
141
Something went wrong with that request. Please try again.