netuitive 0.3.4

Python Client for Netuitive Cloud

===============================
Netuitive Python Client
===============================

|BuildStatus|_ |CoverageStatus|_

.. |BuildStatus| image:: https://travis-ci.org/Netuitive/netuitive-client-python.svg?branch=master
.. _BuildStatus: https://travis-ci.org/Netuitive/netuitive-client-python

.. |CoverageStatus| image:: https://coveralls.io/repos/github/Netuitive/netuitive-client-python/badge.svg?branch=master
.. _CoverageStatus: https://coveralls.io/github/Netuitive/netuitive-client-python?branch=master

| The Netuitive Python Client allows you to push data to `Netuitive <https://www.netuitive.com>`_ using Python. Netuitive provides an adaptive monitoring and analytics platform for cloud infrastructure and web applications.

| For more information, check out the `help docs <https://help.netuitive.com>`_ or contact `support <mailto:[e-mail]>`_.

The Netuitive Python Client can...

* ...create an `element <https://help.netuitive.com/Content/Performance/Elements/elements.htm>`_ in Netuitive with the following data:
* Element Name
* Attributes
* Tags
* Metric Samples
* Element relations
* Location
* Metric Tags

* ...create an `event <https://help.netuitive.com/Content/Events/events.htm>`_ in Netuitive with the following data:
* Element Name
* Event Type
* Title
* Message
* Level
* Tags
* Source

Using the Python Netuitive Client
----------------------------------

Setup the Client
~~~~~~~~~~~~~~~~~

``ApiClient = netuitive.Client(api_key='<my_api_key>')``


Setup the Element
~~~~~~~~~~~~~~~~~~

``MyElement = netuitive.Element()``

Add an Attribute
~~~~~~~~~~~~~~~~~

``MyElement.add_attribute('Language', 'Python')``

Add an Element relation
~~~~~~~~~~~~~~~~~~~~~~~~

``MyElement.add_relation('my_child_element')``

Add a Tag
~~~~~~~~~~

``MyElement.add_tag('Production', 'True')``

Add a Metric Sample
~~~~~~~~~~~~~~~~~~~~

``MyElement.add_sample('cpu.idle', 1432832135, 1, host='my_hostname')``

Add a Metric Sample with a Sparse Data Strategy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``MyElement.add_sample('app.zero', 1432832135, 1, host='my_hostname', sparseDataStrategy='ReplaceWithZero')``

Add a Metric Sample with unit type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``MyElement.add_sample('app.requests', 1432832135, 1, host='my_hostname', unit='requests/s')``

Add a Metric Sample with utilization tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``MyElement.add_sample('app.requests', 1432832135, 1, host='my_hostname', tags=[{'utilization': 'true'}])``

Add a Metric Sample with min/max values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``MyElement.add_sample('app.percent_used', 1432832135, 50, host='my_hostname', unit='percent', min=0, max=100)``

Send the Samples
~~~~~~~~~~~~~~~~~

``ApiClient.post(MyElement)``

Remove the samples already sent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``MyElement.clear_samples()``

Create an Event
~~~~~~~~~~~~~~~~

``MyEvent = netuitive.Event(hst, 'INFO', 'test event','this is a test message', 'INFO')``

Add a Custom Check
~~~~~~~~~~~~~~~~

``MyCheck = netuitive.Check('heartbeat', 'element', 60)``

POST to ``/check/{apiId}/{checkName}/{elementFqn}/{ttl}``

See our `checks documentation <https://docs.metricly.com/alerts-notifications/checks/custom-checks/>`_ for more information about custom check parameters and a cURL example.

Send the Event
~~~~~~~~~~~~~~~

``ApiClient.post_event(MyEvent)``

Check that our local time is set correctly (returns True/False)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``ApiClient.time_insync()``

Docker Example
----------
Included in this project is an example python script (`example/example.py`) which can be built and run within a Docker container. To send test data into your Netuitive environment run the following:

::

docker build -t netuitive-client-python .
docker run -e CUSTOM_API_KEY=<custom-api-key> netuitive-client-python

::

Make sure to use your **Custom** Netuitive datasource API key.

Copyright and License
---------------------

Copyright 2015-2016 Netuitive, Inc. under [the Apache 2.0 license](LICENSE).




History
-------

0.2.3 (2017-02-14)
---------------------

* test_check_time_offset should not be timezone sensitive
* add Example Script Dockerfile
* Handle 403 and other HTTP errors better


0.2.2 (2016-09-30)
---------------------

* fix millisecond timestamps

0.2.1 (2016-09-30)
---------------------

* add support for millisecond timestamps

0.2.0 (2016-07-22)
---------------------

* sanitize metric names

0.1.6 (2016-05-20)
---------------------

* fix handling of http errors

0.1.5 (2016-05-03)
---------------------

* fix the internal version number
* improve handling of http errors

0.1.4 (2016-04-07)
---------------------

* improve HTTP response error handling
* Update Development Status to 4 - Beta

0.1.3 (2016-03-21)
---------------------

* Add user agent to time offset check
* Better handling of null element ids

0.1.2 (2016-03-09)
---------------------

* Fix server time offset check


0.1.1 (2016-03-08)
---------------------

* Add server time offset check
* Fix default event time


0.1.0 (2016-01-27)
---------------------

* Add metric tag support
* Add min/max/avg/sum/cnt support
* Add Element location support
* Test re-factor
* Increase test coverage
* Fix for event support


0.0.9 (2015-12-03)
---------------------

* Add custom client string
* Add relation support


0.0.8 (2015-10-16)
---------------------

* Add event support
* Add Python 3 support


0.0.7 (2015-06-23)
---------------------

* Fix for Preventing duplicate metrics


0.0.6 (2015-06-23)
---------------------

* Add support for Spare Data Strategy and Unit settings for Metrics
* Prevent duplicate metrics
* Documentation improvements


0.0.5 (2015-06-12)
---------------------

* Element type is now easier to set


0.0.3 (2015-06-01)
---------------------

* Fixes for API URL setting


0.0.2 (2015-05-28)
---------------------

* First release on PyPI.