Skip to content
Browse files

First pass at proper docs.

  • Loading branch information...
1 parent fca4db8 commit bec939f9a958c61a6bad20c4cce840a90f3d7eeb James Socol committed
Showing with 1,060 additions and 85 deletions.
  1. +2 −0 MANIFEST.in
  2. +8 −85 README.rst
  3. +153 −0 docs/Makefile
  4. +242 −0 docs/conf.py
  5. +100 −0 docs/configure.rst
  6. +26 −0 docs/index.rst
  7. +190 −0 docs/make.bat
  8. +145 −0 docs/reference.rst
  9. +68 −0 docs/timing.rst
  10. +126 −0 docs/types.rst
View
2 MANIFEST.in
@@ -1 +1,3 @@
include AUTHORS CHANGES LICENSE MANIFEST.in README.rst
+include setup.py
+recursive-include docs *
View
93 README.rst
@@ -2,11 +2,10 @@
A Python statsd client
======================
-`statsd <https://github.com/etsy/statsd>`_ is a friendly front-end to `Graphite
-<http://graphite.wikidot.com/>`_. This is a Python client for the statsd
-daemon.
+statsd_ is a friendly front-end to Graphite_. This is a Python client for the
+statsd daemon.
-To use::
+Quickly, to use::
>>> import statsd
>>> c = statsd.StatsClient('localhost', 8125)
@@ -40,87 +39,11 @@ Or from source::
$ python setup.py install
-In Django
-=========
+Docs
+====
-If you're lucky enough to be using statsd in Django, you can configure a
-default client in your settings module with two values. The defaults are::
+There are lots of docs in the ``docs/`` directory.
- STATSD_HOST = 'localhost'
- STATSD_PORT = 8125
-Then instead of instantiating a new client every time, you can just grab::
-
- >>> from statsd import statsd
- >>> statsd.incr('foo')
-
-You can even set a prefix (optionally)::
-
- STATSD_PREFIX = 'foo'
-
-This can help differentiate between environments, like dev, staging, and
-production.
-
-
-Context Manager
-===============
-
-You can use a ``StatsClient`` instance as a context manager to easily time
-sections of code with the ``timer()`` method::
-
- >>> from statsd import statsd
- >>> with statsd.timer('bar'):
- ... func()
- ... func()
-
-When the managed block exits, the client will automatically send the time it
-took to statsd.
-
-If you'd like to catpure the elapsed time, add a variable to the ``with``
-block::
-
- >>> from statsd import statsd
- >>> with statsd.timer('bar') as timer:
- ... func()
- >>> print timer.ms # Elapsed time in milliseconds.
-
-
-Decorator
-=========
-
-You can *also* use a ``StatsClient`` instance as a decorator, also with the
-``timer()`` method::
-
- >>> from statsd import statsd
- >>> @statsd.timer('bar')
- ... def foo():
- ... pass
-
-Every time ``foo()`` is called, timing information will be sent to the stat
-``bar``.
-
-
-Sample Rates
-============
-
-All methods support an optional ``rate`` (kw)arg. This is a float between 0 and
-1 that specifies what fraction of data to send through (for a specific call).
-Sample rates are recorded by statsd.
-
-For example, here ``foo`` will be incremented approximately 50% of the time::
-
- >>> from statsd import statsd
- >>> statsd.incr('foo', 1, rate=0.5)
-
-Statsd understands that this is a 50% sample rate and will adjust accordingly.
-
-Similarly with ``decr()`` and timings::
-
- >>> from statsd import statsd
- >>> statsd.decr('foo', 1, rate=0.5)
- >>> statsd.timing('foo', 320, rate=0.25)
- >>> with statsd.timer('bar', rate=0.1):
- ... pass
- >>> @statsd.timer('bar', rate=0.5)
- ... def foo():
- ... pass
+.. _statsd: https://github.com/etsy/statsd
+.. _Graphite: http://graphite.wikidot.com/
View
153 docs/Makefile
@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PythonStatsD.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PythonStatsD.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/PythonStatsD"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PythonStatsD"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
View
242 docs/conf.py
@@ -0,0 +1,242 @@
+# -*- coding: utf-8 -*-
+#
+# Python StatsD documentation build configuration file, created by
+# sphinx-quickstart on Mon Apr 9 15:47:23 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Python StatsD'
+copyright = u'2012, James Socol'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.4.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.4.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PythonStatsDdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'PythonStatsD.tex', u'Python StatsD Documentation',
+ u'James Socol', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'pythonstatsd', u'Python StatsD Documentation',
+ [u'James Socol'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'PythonStatsD', u'Python StatsD Documentation',
+ u'James Socol', 'PythonStatsD', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
View
100 docs/configure.rst
@@ -0,0 +1,100 @@
+.. _configuring-chapter:
+
+==================
+Configuring Statsd
+==================
+
+It's easy to configure and use Statsd at runtime, but there are also two
+shortcuts available.
+
+
+Runtime
+=======
+
+If you are running the statsd_ server locally and on the default port, it's
+extremely easy::
+
+ from statsd import StatsClient
+
+ statsd = StatsClient()
+ statsd.incr('foo')
+
+There are three arguments to configure your ``StatsClient`` instance. They, and
+their defaults, are::
+
+ from statsd import StatsClient
+
+ statsd = StatsClient(host='localhost',
+ port=8125,
+ prefix=None)
+
+``host`` is the host running the statsd server. It will support any kind of
+name or IP address you might use.
+
+``port`` is the statsd server port. The default for both server and client is
+``8125``.
+
+``prefix`` helps distinguish multiple applications or environments using the
+same statsd server. It will be prepended to all stats, automatically. For
+example::
+
+ from statsd import StatsClient
+
+ foo_stats = StatsClient(prefix='foo')
+ bar_stats = StatsClient(prefix='bar')
+
+ foo_stats.incr('baz')
+ bar_stats.incr('baz')
+
+will produce two different stats, ``foo.baz`` and ``bar.baz``. Without the
+``prefix`` argument, or with the same ``prefix``, two ``StatsClient`` instances
+will update the same stats.
+
+
+In Django
+=========
+
+If you are using Statsd in a Django_ application, you can configure a default
+``StatsClient`` in the Django settings. All of these settings are optional.
+
+Here are the settings and their defaults::
+
+ STATSD_HOST = 'localhost'
+ STATSD_PORT = 8125
+ STATSD_PREFIX = None
+
+You can use the default ``StatsClient`` simply::
+
+ from statsd import statsd
+
+ statsd.incr('foo')
+
+This instance will use the settings, if provided by Django. If no Django
+settings can be imported, it won't be available.
+
+
+From the Environment
+====================
+
+Statsd isn't only useful in Django or on the web. A default instance will also
+be available if you configure at least two environment variables. These do not
+have defaults.
+
+You can set these variables in the environment::
+
+ STATSD_HOST
+ STATSD_PORT
+ STATSD_PREFIX
+
+and then in your Python application, you can simply do::
+
+ from statsd import statsd
+
+ stats.incr('foo')
+
+**NB**: To make this default instance available, you will need to set at least
+``STATSD_HOST`` and ``STATSD_PORT``, even if using the default values of
+``localhost`` and ``8125``.
+
+.. _statsd: https://github.com/etsy/statsd
+.. _Django: https://www.djangoproject.com/
View
26 docs/index.rst
@@ -0,0 +1,26 @@
+.. Python StatsD documentation master file, created by
+ sphinx-quickstart on Mon Apr 9 15:47:23 2012.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to Python StatsD's documentation!
+=========================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ configure.rst
+ types.rst
+ timing.rst
+ reference.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
View
190 docs/make.bat
@@ -0,0 +1,190 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PythonStatsD.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PythonStatsD.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+:end
View
145 docs/reference.rst
@@ -0,0 +1,145 @@
+.. _reference-chapter:
+
+=============
+API Reference
+=============
+
+The ``StatsClient`` provides accessors for all the types of data the statsd_
+server supports.
+
+**NB:** Each public API method supports a ``rate`` parameter, but statsd
+doesn't always use it the same way. See the :ref:`types-chapter` for more
+information.
+
+
+.. _StatsClient:
+
+``StatsClient``
+===============
+
+::
+
+ StatsClient(host='localhost', port=8125, prefix=None)
+
+Create a new ``StatsClient`` instance with the appropriate connection and
+prefix information.
+
+* ``host``: the hostname or IP (v4/v6) address of the statsd_ server.
+
+* ``port``: the port of the statsd server.
+
+* ``prefix``: a prefix to distinguish and group stats from an application or
+ environment
+
+
+.. _incr:
+
+``incr``
+========
+
+::
+
+ StatsClient().incr(stat, count=1, rate=1)
+
+Increment a :ref:`counter <counter-type>`.
+
+* ``stat``: the name of the counter to increment.
+
+* ``count``: the amount to increment by. Typically an integer. May be negative,
+ but see also :ref:`decr`.
+
+* ``rate``: a sample rate, a float between 0 and 1. Will only send data this
+ percentage of the time. The statsd server will take the sample rate into
+ account for counters.
+
+
+.. _decr:
+
+``decr``
+========
+
+::
+
+ StatsClient().decr(stat, count=1, rate=1)
+
+Decrement a :ref:`counter <counter-type>`.
+
+* ``stat``: the name of the counter to decrement.
+
+* ``count``: the amount to decrement by. Typically an integer. May be negative
+ but that will have the impact of incrementing the counter. See also
+ :ref:`incr`.
+
+* ``rate``: a sample rate, a float between 0 and 1. Will only send data this
+ percentage of the time. The statsd server will take the sample rate into
+ account for counters.
+
+
+.. _timing:
+
+``timing``
+==========
+
+::
+
+ StatsClient().timing(stat, delta, rate=1)
+
+Record :ref:`timer <timer-type>` information.
+
+* ``stat``: the name of the timer to use.
+
+* ``delta``: the number of milliseconds whatever action took. Should always be
+ milliseconds.
+
+* ``rate``: a sample rate, a float between 0 and 1. Will only send data this
+ percentage of the time. The statsd server does *not* take the sample rate
+ into account for timers.
+
+
+.. _timer:
+
+``timer``
+=========
+
+::
+
+ with StatsClient().timer(stat, rate=1):
+ pass
+
+::
+
+ @StatsClient().timer(stat, rate=1)
+ def foo():
+ pass
+
+Automatically ecord timing information for a managed block or function call.
+See also the :ref:`chapter on timing <timing-chapter>`.
+
+* ``stat``: the name of the timer to use.
+
+* ``rate``: a sample rate, a float between 0 and 1. Will only send data this
+ percentage of the time. The statsd server does *not* take the sample rate
+ into account for timers.
+
+
+.. _gauge:
+
+``gauge``
+=========
+
+::
+
+ StatsClient().gauge(stat, value, rate=1)
+
+Set a :ref:`gauge <gauge-type>` value.
+
+* ``stat``: the name of the gauge to set.
+
+* ``value``: the current value of the gauge.
+
+* ``rate``: a sample rate, a float between 0 and 1. Will only send data this
+ percentage of the time. The statsd server does *not* take the sample rate
+ into account for gauges. Use with care.
+
+
+.. _statsd: https://github.com/etsy/statsd
View
68 docs/timing.rst
@@ -0,0 +1,68 @@
+.. _timing-chapter:
+
+============
+Using Timers
+============
+
+:ref:`Timers <timers>` are an incredibly powerful tool for tracking application
+performance. Statsd provides a number of ways to use them to instrument your
+code.
+
+
+Calling ``timing`` manually
+===========================
+
+The simplest way to use a timer is to record the time yourself and send it
+manually, using the :ref:``timing`` method::
+
+ import time
+ from statsd import StatsClient
+
+ statsd = StatsClient()
+
+ start = time.time()
+ time.sleep(3)
+
+ # You must convert to milliseconds:
+ dt = int((time.time() - start) * 1000)
+ statsd.timing('slept', dt)
+
+
+Using a context manager
+=======================
+
+Each ``StatsClient`` instance contains a :ref:``timer`` attribute that can be
+used as a context manager or a decorator. When used as a context manager, it
+will automatically report the time taken for the inner block::
+
+ from statsd import StatsClient
+
+ statsd = StatsClient()
+
+ with stats.timer('foo'):
+ # This block will be timed.
+ for i in xrange(0, 100000):
+ i ** 2
+ # The timing is sent immediately when the managed block exits.
+
+
+Using a decorator
+=================
+
+The ``timer`` attribute can also be used as a function decorator. Every time
+the decorated function is called, the time it took to execute will be sent to
+the statsd server.
+
+::
+
+ from statsd import StatsClient
+
+ statsd = StatsClient()
+
+ @statsd.timer('myfunc')
+ def myfunc(a, b):
+ """Calculate the most complicated thing a and b can do."""
+
+ # Timing information will be sent every time the function is called.
+ myfunc(1, 2)
+ myfunc(3, 7)
View
126 docs/types.rst
@@ -0,0 +1,126 @@
+.. _types-chapter:
+
+==========
+Data Types
+==========
+
+The statsd_ server supports a number of different data types, and performs
+different aggregation on each of them. The three main types are *counters*,
+*timers*, and *gauges*.
+
+The statsd server collects and aggregates in 30 second intervals before
+flushing to Graphite_. Graphite usually stores the most recent data in 1-minute
+averaged buckets, so when you're looking at a graph, for each stat you are
+typically seing the average value over that minute.
+
+
+.. _counter-type:
+
+Counters
+========
+
+*Counters* are the most basic and default type. They are treated as a count of
+a type of event per second, and are, in Graphite_, typically averaged over one
+minute. That is, when looking at a graph, you are usually seeing the average
+number of events per second during a one-minute period.
+
+The statsd server collects counters under the ``stats`` prefix.
+
+Counters are managed with the :ref:``incr`` and :ref:``decr`` methods of
+``StatsClient``::
+
+ from statsd import StatsClient
+
+ statsd = StatsClient()
+
+ statsd.incr('some.event')
+
+You can increment a counter by more than one by passing a second parameter::
+
+ statsd.incr('some.other.event', 10)
+
+You can also use the ``rate`` parameter to produce sampled data. The statsd
+server will take the sample rate into account, and the ``StatsClient`` will
+only send data ``rate`` percent of the time. This can help the statsd server
+stay responsive with extremely busy applications.
+
+``rate`` is a float between 0 and 1::
+
+ # Increment this counter 10% of the time.
+ statsd.incr('some.third.event', rate=0.1)
+
+Because the statsd server is aware of the sampling, it will still show you the
+true average rate per second.
+
+You can also decrement counters. The ``decr`` method takes the same arguments
+as ``incr``::
+
+ statsd.decr('some.other.event')
+ # Decrease the counter by 5, 15% sample.
+ statsd.decr('some.third.event', 5, rate=0.15)
+
+
+.. _timer-type:
+
+Timers
+======
+
+*Timers* are meant to track how long something took. They are an invaluable
+tool for tracking application performance.
+
+The statsd server collects all timers under the ``stats.timers`` prefix, and
+will calculate the lower bound, mean, 90th percentile, upper bound, and count
+of each timer for each period (by the time you see it in Graphite, that's
+usually per minute).
+
+* The *lower bound* is the lowest value statsd saw for that stat during that
+ time period.
+
+* The *mean* is the average of all values statsd saw for that stat during that
+ time period.
+
+* The *90th percentile* is a value *x* such that 90% of all the values statsd
+ saw for that stat during that time period are below *x*, and 10% are above.
+ This is a great number to try to optimize.
+
+* The *upper bound* is the highest value statsd saw for that stat during that
+ time period.
+
+* The *count* is the number of timings statsd saw for that stat during that
+ time period. It is not averaged.
+
+The statsd server only operates in millisecond timings. Everything should be
+converted to milliseconds.
+
+The ``rate`` parameter will sample the data being sent to the statsd server,
+but in this case it doesn't make sense for the statsd server to take it into
+account (except possibly for the *count* value, but then it would be lying
+about how much data it averaged).
+
+See the :ref:`timing documentation <timing-chapter>` for more detail on using
+timers with Statsd.
+
+
+.. _gauge-type:
+
+Gauges
+======
+
+*Gauges* are a constant data type. They are not subject to averaging, and they
+don't change unless you change them. That is, once you set a gauge value, it
+will be a flat line on the graph until you change it again.
+
+Gauges are useful for things that are already averaged, or don't need to reset
+periodically. System load, for example, could be graphed with a gauge. You
+might use ``incr`` to count the number of logins to a system, but a gauge to
+track how many active WebSocket connections you have.
+
+The statsd server collects gauges under the ``stats.gauges`` prefix.
+
+The :ref:``gauge`` method also support the ``rate`` parameter to sample data
+back to the statsd server, but use it with care, especially with gauges that
+may not be updated very often.
+
+
+.. _statsd: https://github.com/etsy/statsd
+.. _Graphite: http://graphite.wikidot.com/

0 comments on commit bec939f

Please sign in to comment.
Something went wrong with that request. Please try again.