.. _1-1-1:

1.1.1
===========================
*12/21/2017*

Graphite 1.1.1 is now available! This marks another major milestone on Graphite's releases.

Source bundles are available from GitHub:

* https://github.com/graphite-project/graphite-web/archive/1.1.1.tar.gz
* https://github.com/graphite-project/carbon/archive/1.1.1.tar.gz
* https://github.com/graphite-project/whisper/archive/1.1.1.tar.gz
* https://github.com/graphite-project/carbonate/archive/1.1.1.tar.gz

Graphite can also be installed from `PyPI <http://pypi.python.org/>`_ via
`pip <http://www.pip-installer.org/en/latest/index.html>`_. PyPI bundles are here:

* http://pypi.python.org/pypi/graphite-web/
* http://pypi.python.org/pypi/carbon/
* http://pypi.python.org/pypi/whisper/
* http://pypi.python.org/pypi/carbonate/


The main feature of this release is :ref:`tag support <tags>` in Carbon and Graphite-web. From the release of the 1.1.x series, Graphite supports storing data using tags to identify each series. This allows for much more flexibility than the traditional hierarchical layout. When using tag support, each series is uniquely identified by its name and set of tag/value pairs. We also have new functions (``seriesByTags``, ``groupByTags`` and ``aliasByTags``) for querying tagged series, and support for using tags in all existing aggregation & grouping functions.

All components of Graphite stack now support Python 3. Python 3 support is however considered experimental, as this is the first release with complete Python 3 support.

Another long-awaited feature is :ref:`custom functions <function-plugins>` - you can write your own functions and load them into Graphite. There's also the :ref:`Function API <function-api>` to get a list of available functions, or the details of a specific function. Please note that the built-in frontend code does not yet use the Functions API, so your functions will not be present in the Graphite-web interface.

Graphite 1.1.1 also has completely refactored clustering code - for example, now clustering can use `msgpack`_ format for intra-cluster communications and supports buffering HTTP when talking to cluster servers, which should `increase the reading speed`_. If you're using custom finders you can use :ref:`new documentation <advanced-finders>` to make your code use the new features too.

Graphite now supports "pipe" chaining syntax for functions. With this update the following query ``aliasByNode(movingAverage(sortByName(test.*),"5min"),1)`` can be written as ``test.*|sortByName()|movingAverage("5min")|aliasByNode(1)``.  See `PR#2042`_ for details.

New function ``xFilesFactor`` which sets the xFilesFactor for runtime aggregation and consolidation, also aggregation functions (`moving*` and new ``aggregate`` function) now supporting ``xFilesFactor`` explicitly - see `PR#2053`_ for details.

A host of other new features, bug fixes and changes are in the list below.


New features
------------

* Tagging support / Tags Autocompletion / TagDB Federation (PR#2002 / PR#2078 / PR#2128, @DanCech)

* Python3 support (PR#2139, @takluyver)

* Custom functions (PR#2146, @DanCech)

* Buffering support in clustering (PR#2136, @woodsaj / @DanCech)

* Msgpack support for clustering (PR#2123, @DanCech)

* New ``CLUSTER_SERVERS`` format (proto, format and local parameters (PR#2123, @DanCech)

* New custom storage backends mechanics (PR#2093 / PR#2103 / PR#2128, @DanCech)

* Move /metrics/index.json handling into finders & use worker pool (PR#2103, @DanCech)


Functions
---------

* :ref:`Custom functions <function-plugins>` (PR#2146, @DanCech)

* Use timezone-aware dates in ``hitcount``, update epoch to handle naive dates (PR#2088, @DanCech)

* Added check for empty series list on ``percentileOfSeries`` (PR#2089, @melnikk)

* Improve efficiency of ``linearRegression``, ``timeShift``, ``timeStack`` & ``useSeriesAbove`` (PR#2072, @DanCech)

* Implement ``unique()`` (PR#2063, @DanCech)

* Support using tags in functions that accept nodes (PR#2055, @DanCech)

* "Pipe" function chaining syntax (`PR#2042`_, @DanCech)

* xFilesFactor support, add aggregate function (`PR#2053`_, @DanCech)

* Support matching series by node in ``asPercent`` (PR#2050, @DanCech)

* Add ``aggregateWithWildcards`` function, minor refactor for ``movingWindow`` (PR#2044, @DanCech)

* Add ``/tags/findSeries``, add filter and pretty parameters to tag list/details endpoints (PR#2034, @DanCech)

* Implement ``movingWindow`` & round functions, tidy up other "moving" functions (PR#2032, @DanCech)

* Improve efficiency of ``summarize`` and ``smartSummarize`` functions (PR#1916, @DanCech)

* Add first and last to ``consolidateBy`` functions (PR#2030, @DanCech)

* Fix ``perSecond`` null handling, use explicit integer division (PR#2029, @DanCech)

* ``Min-Max`` Normalization Function (PR#2011, @msk610)

* Enable advanced alignment for ``smartSummarize`` (PR#2021, @luigiberrettini)

* add ``filterSeries``, ``highest``, ``lowest`` & ``sortBy`` functions (PR#2146, @DanCech)


Frontend changes
----------------

* Add a history button to the dashboard kind of like Cacti (PR#2100, @cbowman0)

* Manipulate graph targets and implement New Graph -> New Empty Graph (PR#424, @cbowman0)

* JS linting (@cbowman)


Other new features
------------------

* Set pathExpression on ``seriesByTag`` results (PR#2124, @DanCech)

* Aggregate points from carbon cache like whisper (PR#2082, @DanCech)

* Use ``WEBAPP_VERSION`` in documentation link (@wridgers)

* Add a history button to the dashboard kind of like Cacti (PR#2100, @cbowman0)

* Support sending logs to stderr (PR#2066, @DanCech)

* Improve parseATTime (PR#2070, @DanCech)

* Update metrics/find to support the same from/until specifications as render (@DanCech)

* Improve rendering performance dramatically in certain situations (upstream issue #770) (@powo)


Bug Fixes
---------

* Add median adjustment for even length arrays (PR#2132, @shanson7)

* Use default tagdb if ``TAGDB`` setting is not set (@woodsaj)

* Get rid of OverflowError in perSecond and scaleToSeconds (PR#2127, @Felixoid)

* Document week / w suffix (PR#2107, @mcv21)

* Add ``REMOTE_USER_MIDDLEWARE`` configuration option and fix ``REMOTE_USER_BACKEND`` documentation (PR#2091, @wridgers)

* Fix the url values to match the current document.body.dataset.baseUrl (PR#2087, @cbowman0)

* Whisper reader strange results for counters after merge_with_carbonlink (PR#2082, @olevchyk / @DanCech)

* Handle no data with graphType=pie (PR#2071, @cbowman0)

* CarbonLink cache-query return 0 datapoints in some cases (PR#2012, @leochen4891)

* Render view refactor & maxDataPoints=1 (PR#2054, @DanCech)

* Fix consolidation (PR#2052, @DanCech / @powo)

* Add median adjustment for even length arrays (@shanson7)

* Get rid of OverflowError in perSecond and scaleToSeconds (@Felixoid)

* Clean up perSecond and nonNegativeDerivative maxValue and None handling (@DanCech)

* Use ``WEBAPP_VERSION`` in documentation link (@wridgers)

* Fnv1a fixes (PR#2014, @olevchyk)

* Fix divideByZero when FIND_CACHE_DURATION=0 (@woodsaj)


Upgrading
---------
Graphite-Web requires Python 2.7 or newer and Django version 1.8 - 1.11 (Python3 supported only in Django 1.11). Carbon requires Twisted version 13.2 or newer. For AMQP support txAMQP version 0.8 is required now. There are a number of new features in this release, but we've been careful to avoid any behavioral regressions in the default settings files. You'll want to review the new Graphite-Web and Carbon service options in the ``local_settings.py.example`` and ``carbon.conf.example`` files, respectively, before merging those into your production configurations. Please also check :doc:`config file documentation </config-local-settings>`

If you're not already running from the *master* branch, Graphite-Web's application database will need to be upgraded . It's a good idea to backup the database before proceeding with the migration. The following steps will upgrade a SQLite database:

.. code-block:: none

  sudo cp /opt/graphite/storage/graphite.db \
        /opt/graphite/storage/graphite.db.backup-`date +%Y%m%d_%H%M%S`
  sudo PYTHONPATH=/opt/graphite/webapp django-admin.py migrate \
        --noinput --settings=graphite.settings --fake-initial

In this release of Graphite-Web, migrations have been added for any Django models that did not have them. Previously, if using Django 1.9 or later, one needed the ``--run-syncdb`` option for migrate to create tables for Graphite-Web models without migrations (and Django 1.8 or earlier did not have this option but always exhibited this behavior). Django keeps track of which migrations have been applied and attempts to run any that have not, and these new initial migrations try to create tables that already exist from previous versions of Graphite-Web, and fail. This common Django situation is resolved by the ``--fake-initial`` option for migrate: it considers an initial migration to already be applied if the tables it creates already exist.


Other Changes
-------------

Graphite-Web
^^^^^^^^^^^^

* Clean up a few codacy issues (PR#2140, @cbowman0)

* Add more tests for render/datalib.py (PR#2086, @cbowman0)

* Fix caching in _merge_results and add tests (PR#2085, @cbowman0)

* Update render_api.rst (@r3cgm)

* Use prefetch logic for sub-requests (PR#2076, @DanCech)

* Test class PrefetchedData (PR#2079, @cbowman0)

* Fix example vhost filename (@rednixon)

* Basic tests for render/datalib's ``_merge_results()`` (PR#2075, @cbowman0)

* Whisper reader updates (PR#2074, @DanCech)

* Improve test reliability (PR#2056, @DanCech)

* Add more test coverage for render/functions (PR#2068, @cbowman0)

* Add ``timeshift`` test coverage (PR#2065, @cbowman0)

* Increasing test coverage for functions (PR#2011, @msk610)

* Update metrics/find to support the same from/until specifications as render (@DanCech)


Carbon
^^^^^^

* Py3 compatibility fixes (@piotr1212)

* Catch TypeError exception from None data value (@retzkek)

* Added '--logger' and '--logfile' option (Du Zheng / @deniszh)

* Fixing lint (@DanCech)

* Fix listening on IPv6 interfaces (PR#683, @mk-fg)

* Tags support (@DanCech)

* Fix fnv1a support (PR#679, @olevchyk)


Whisper
^^^^^^^

* Whisper-fetch: add --time-format option (PR#235, @xavierog)

* Added test and fix for broken assert in whisper.__archive_update_many (@wk86 / @DanCech)

* Don't use shell for whisper-resize.py calls (PR#241, @eserte)


Carbonate
^^^^^^^^^

* Passing empty list for nodes seems to work (PR#87, @olevchyk)


.. _msgpack: https://msgpack.org/
.. _increase the reading speed: https://github.com/graphite-project/graphite-web/issues/2142#issuecomment-349249348
.. _PR#2042: https://github.com/graphite-project/graphite-web/pull/2042
.. _PR#2053: https://github.com/graphite-project/graphite-web/pull/2053
