Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added README.txt for pip.

  • Loading branch information...
commit 3d693c6004e386104d50563cb3bcd2e3d279c280 1 parent 70ec9cf
@gaelenh authored
Showing with 171 additions and 1 deletion.
  1. +165 −0 README.txt
  2. +4 −0 makedoc.sh
  3. +2 −1  setup.py
View
165 README.txt
@@ -0,0 +1,165 @@
+Python StatsD Client
+====================
+
+`StatsD <https://github.com/etsy/statsd>`_ is a stats server that plays
+with `Graphite <http://graphite.wikidot.com/>`_. Together, they collect,
+aggregate, and show stats. If you don't know what either of those are,
+well, why are you still reading this? If you write software or know
+someone that does, I bet collecting stats will make your software
+better, or at the very least give you something to look at and think
+about. StatsD makes it really easy to send stats within your code. This
+client maks it even easier to get stats out of your python code.
+
+Install
+-------
+
+Annoyed with managing external packages? There are plenty of statsd
+clients that come up under 'pip search statsd'. Who has time to keep
+track of tiny dependencies for small projects? Just copy statsd.py into
+your project if you're into that kind of thing. No need to depend on
+some multi-file package for what should be a simple client. Grab and Go!
+If you're a stickler for dependencies, you probably don't need to know
+how to install this, but here you go any how:
+
+Clone and install:
+
+::
+
+ git clone git@github.com:gaelenh/python-statsd-client.git
+ cd python-statsd-client
+ python setup.py install
+
+Install with pip:
+
+::
+
+ pip install statsd-client
+
+Or like I said above, just copy statsd.py into your code base.
+
+Usage
+-----
+
+Basic
+~~~~~
+
+Setup is easy. By default, the client will connect to localhost on the
+default statsd port (8125).
+
+::
+
+ import statsd
+ statsd.incr('processed') # Increment processed bucket by 1
+ statsd.incr('processed', 5) # This time by 5
+ statsd.incr('processed', sample_rate=0.9) # Increment with a sample rate of .9
+ statsd.timing('pipeline', 2468.34) # Pipeline took 2468.34 ms to execute
+
+Want to connect to a non-local statsd? Use
+statsd.init\_statsd(settings). Settings is a dict with any of these
+keys:
+
+::
+
+ STATSD_HOST (Default 'localhost'): String host name.
+ STATSD_PORT (Default 8125): Integer port number.
+ STATSD_SAMPLE_RATE (Default None (same as 1.0)): Integer/Float between 0 and 1.
+ STATSD_BUCKET_PREFIX (Default None): String prefix added to all buckets. The code will handle dotting them together.
+
+If you do not want to use init\_statsd, you can always pass in your
+settings when you create the clients, timers or counters:
+
+::
+
+ from statsd import StatsdClient
+ client = StatsdClient(host='127.0.0.1', port=9999, prefix='app', sample_rate=0.9)
+
+Counters
+~~~~~~~~
+
+Want to count things? Use StatsdCounter:
+
+::
+
+ import statsd
+ statsd.init_statsd({'STATSD_BUCKET_PREFIX': 'photos'})
+ counter = statsd.StatsdCounter('processed')
+ # calls on counter will send updates to bucket named 'photos.processed'
+ counter += 1 # equivalent to counter.incr() or counter.incr(1)
+ counter += 5 # equivalent to counter.incr(5)
+ counter -= 10 # equivalent to counter.decr(10)
+
+Timing
+~~~~~~
+
+Interested in timing? Check out all the ways you can time things:
+
+::
+
+ import statsd
+ statsd.init_statsd({'STATSD_BUCKET_PREFIX': 'photos'})
+ timer = statsd.StatsdTimer('pipeline')
+ timer.start()
+ # Do stuff
+ timer.split('stage1') # Sends timing data for bucket 'photos.pipeline.stage1'
+ # Do more stuff
+ timer.split('stage2') # Sends timing data for bucket 'photos.pipeline.stage2'
+ # Do even more stuff
+ timer.stop() # Sends timing data for bucket 'photos.pipeline.total'
+
+Timers can be used as decorators too:
+
+::
+
+ from statsd import StatsdTimer
+ @StatsdTimer.wrap('pipeline')
+ def process():
+ pass
+ process() # Sends timing data for bucket 'pipeline.total'
+
+Fancy with statement usage!
+
+::
+
+ from statsd import StatsdTimer
+ with StatsdTimer('photos'):
+ pass # Do stuff
+
+Even fancier:
+
+::
+
+ from statsd import StatsdTimer
+ with StatsdTimer('photos') as t:
+ # Do stuff
+ t.split('stage1')
+ # Do more stuff
+ t.split('stage2')
+ # Finish up
+
+Using timers with decorators or the with statement will still sends
+stats if an exception is raised in the code block:
+
+::
+
+ from statsd import StatsdTimer
+ class Foo(object):
+ @StatsdTimer('photos')
+ def proc(self):
+ # Do stuff
+ raise ValueError('Whoops')
+ f = Foo()
+ f.proc() # Raises exception, but sends timing data for bucket 'photos.total-except'
+
+Misc
+----
+
+The client integrates great with `Flask <http://flask.pocoo.org/>`_.
+Just call statsd.init\_statsd when you're initializing all your other
+framework components. Once that's done, you can use the timers and
+counters anywhere in your code.
+
+Contributing
+------------
+
+If you find a bug and want to fix it, fork, branch, and submit a pull
+request. The master branch will always have the latest working code.
View
4 makedoc.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+pandoc -f markdown -t rst -o README.txt README.md
+
View
3  setup.py
@@ -8,7 +8,7 @@
def main():
cwd = os.path.dirname(os.path.abspath(__file__))
- path = os.path.join(cwd, 'README.md')
+ path = os.path.join(cwd, 'README.txt')
readme = open(path, 'rb').read()
setup(name='statsd-client',
@@ -18,6 +18,7 @@ def main():
license='Apache 2.0',
author='Gaelen Hadlett',
author_email='gaelenh@gmail.com',
+
url='https://github.com/gaelenh/python-statsd-client',
py_modules=['statsd'],
keywords=['statsd', 'graphite', 'stats'],
Please sign in to comment.
Something went wrong with that request. Please try again.