README
======

A python library to send application metrics using UDP.

.. image:: https://travis-ci.org/globocom/measures.svg?branch=master
   :target: https://travis-ci.org/globocom/measures
   :alt: Build Status


Installation
------------

.. code-block:: bash

    pip install measures


Usage
-----

* count

.. code-block:: python

    from measures import Measure
    measure = Measure('myclient', ('localhost', 1984))
    measure.count('mymetric', dimensions={'name': 'john'})

* time (measure time spent on a given block)

.. code-block:: python

    import time
    from measures import Measure
    measure = Measure('myclient', ('localhost', 1984))
    with measure.time('mymetric'):
        # do some slow operation:
        time.sleep(3.14159)

.. code-block:: python

    import time
    from measures import Measure
    measure = Measure('myclient', ('localhost', 1984))
    with measure.time('mymetric') as dimensions:
        # do some slow operation:
        time.sleep(1.61803)
        # add any relevant information, if necessary:
        dimensions['relevant_info'] = 'pertinent_info'


* send

.. code-block:: python

    from measures import Measure
    measure = Measure('myclient', ('localhost', 1984))
    dimensions = {
        'time': 10.1,
        'relevant_info': pertinent_info
    }
    measure.send('mymetric', dimensions)

* multiple destinations

Metrics can be sent to more than one backend

.. code-block:: python

    from measures import Measure

    measure = Measure('myclient', [('backend.host.1', 1984), ('backend.host.2', 1984)]


Contributing
------------

* Set up your environment

.. code-block:: bash

    git clone https://github.com/globocom/measures.git
    cd measures
    mkvirtualenv measures
    pip install -r test_requirements.txt

* Run the tests

.. code-block:: bash

    make tests

* Write tests for your new feature or bug fix
* Write needed code changes
* Iterate, have fun :)
* Make a pull request with your changes


Who do I talk to?
-----------------

* File an issue at https://github.com/globocom/measures or contact us at
  busca@corp.globo.com
