1.. _1-0-0: 2 31.0.0 4=========================== 5*04/12/2017* 6 7Graphite 1.0.0 is now available for usage. This marks the first release of Graphite's main line in many years. Also, there's a new *optional* component available: Carbonate, a suite of tools for managing and rebalancing Whisper files. 8 9Most users will only need to install the Graphite-Web, Carbon, and Whisper components. 10 11Source bundles are available from GitHub: 12 13* https://github.com/graphite-project/graphite-web/archive/1.0.0.tar.gz 14* https://github.com/graphite-project/carbon/archive/1.0.0.tar.gz 15* https://github.com/graphite-project/whisper/archive/1.0.0.tar.gz 16* https://github.com/graphite-project/carbonate/archive/1.0.0.tar.gz 17 18Graphite can also be installed from `PyPI <http://pypi.python.org/>`_ via 19`pip <http://www.pip-installer.org/en/latest/index.html>`_. PyPI bundles are here: 20 21* http://pypi.python.org/pypi/graphite-web/ 22* http://pypi.python.org/pypi/carbon/ 23* http://pypi.python.org/pypi/whisper/ 24* http://pypi.python.org/pypi/carbonate/ 25 26Upgrading 27--------- 28Graphite-Web requires Python 2.7 or newer and Django version 1.9. Carbon requires Twisted version 13.2 or newer. There are a number of new features in this release, but we've been careful to avoid any behaviorial 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. 29 30If 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: 31 32.. code-block:: none 33 34 sudo cp /opt/graphite/storage/graphite.db \ 35 /opt/graphite/storage/graphite.db.backup-`date +%Y%m%d_%H%M%S` 36 sudo PYTHONPATH=/opt/graphite/webapp django-admin.py migrate \ 37 --noinput --settings=graphite.settings --run-syncdb 38 39A new document is available for :doc:`developers and contributors <../development>` that covers how to setup your own development environment, and running & writing tests. 40 41We're also happy to publish a new document for :doc:`Graphite Events <../events>`. It covers the storage, creation, retrieval, and management of events used for annotation or tracking release-style events. 42 43 44Security Notes 45-------------- 46 47* XSS issue affecting saved graph definitions. Targets are now properly sanitized before being handed back to the user. 48 49 50New Render Functions 51-------------------- 52 53See the :doc:`functions documentation <../functions>` for more information. 54 55* ``aggregateLine`` 56* ``applyByNode`` 57* ``averageOutsidePercentile`` 58* ``delay`` 59* ``exponentialMovingAverage`` 60* ``fallbackSeries`` 61* ``grep`` 62* ``groupByNodes`` 63* ``integralByInterval`` 64* ``interpolate`` 65* ``invert`` 66* ``isNonNull`` 67* ``linearRegression`` 68* ``linearRegressionAnalysis`` 69* ``mapSeries`` 70* ``movingMin`` 71* ``movingMax`` 72* ``movingSum`` 73* ``multiplySeriesWithWildcards`` 74* ``offsetToZero`` 75* ``pow`` 76* ``powSeries`` 77* ``reduceSeries`` 78* ``removeBetweenPercentile`` 79* ``removeEmptySeries`` 80* ``sortByTotal`` 81* ``squareRoot`` 82* ``timeSlice`` 83* ``verticalLine`` 84* ``weightedAverage`` 85 86 87New Display Formats 88------------------- 89 90* ``pdf`` 91* ``dygraph`` 92* ``rickshaw`` 93 94 95New Graph Parameters 96-------------------- 97 98* ``hideNullFromLegend`` 99* ``hideXAxis`` 100* ``noNullPoints`` 101* ``pieLabels`` 102* ``valueLabels`` 103* ``valueLabelsColor`` 104* ``valueLabelsMin`` 105 106 107Bug Fixes 108--------- 109 110Graphite-Web 111^^^^^^^^^^^^ 112 113* Render infinite values correctly for compatibility with JSON consumers (e.g. Grafana). 114 115* Fix for ``aliasByMetric`` to handle trailing parentheses properly. 116 117* Some functions would not handle ``event`` tags formatting. The format for these strings has been fixed. 118 119* Improved data extraction from CarbonLink cache when crossing archive boundaries. 120 121* Follow symlinks for RRD files. 122 123* Unicode fixes for RRD paths. 124 125* Support for the FNV1a_ch hashing algorithm used by the `carbon-c-relay <https://github.com/grobian/carbon-c-relay>`_ project. 126 127* Fix for ``smartSummarize`` where it would discard timezone information, sometimes resulting in an exception due to broken intervals. 128 129* Better handling for missing data in the divisor series for ``divideSeries``. 130 131* Fix function name reported in path expression for ``stdev``. 132 133* The ``countSeries`` function will now return zeroes instead of an empty series. 134 135* The ``constantLine`` function can now be rendered without any other series. 136 137* Incorrect float format across a variety of functions. 138 139* Fix "thousands" unit for y-axis. 140 141* Average/current/max/min Above/Below functions not fails if there is no data. 142 143* Fix blank space below the legend 144 145* Update the command to setup a new database 146 147* aliasByNode(): support all chars allowed by the grammar 148 149Carbon 150^^^^^^ 151 152* Avoid duplication of aggregator statistics by using a dedicated pipeline. 153 154* Log incorrect schemas missing the ``retentions`` attribute. 155 156* Improved logging for writer create or update failures. 157 158* Fix long-standing issue with negative cache size statistic. 159 160* Use the correct ``AGGREGATION_RULES`` configuration file. 161 162* Fix race condition possible when queue is full and destinations reconnect. 163 164* Fix ``--profile`` option for recording performance data. 165 166* Improved help documentation in the Composer. 167 168* Compute seconds_left rightly in util. 169 170* Better handling for failed creates. 171 172* Import manhole and amqp correctly 173 174* Fix CacheManagementHandler() and associated tests 175 176Whisper 177^^^^^^^ 178 179* remove xFilesFactor float comparison, use whisper-resize if whisper-resize.py is not available 180 181* (fix) [FreeBSD-i386] correct size of off_t in posix_fallocate call 182 183* whisper-auto-resize.py: error fix 184 185* double-fix bad commit to whisper-resize 186 187* whisper-auto-resize: fix default values for xFilesFactor and aggregationMethod 188 189* Fix indentation on CACHE_HEADERS, not related to AUTOFLUSH 190 191* rrd2whisper: fix relative destinationpaths 192 193Other Changes 194------------- 195 196Graphite-Web 197^^^^^^^^^^^^ 198 199* Brand new clustering implementation using a pool of worker threads and persistent connections to backends 200 201* New Graphite logo in the Composer banner. 202 203* Pluggable storage finders have been added. This allows graphite to fetch data from other datastores than Whisper or Ceres. See the :doc:`storage finder docs <../storage-backends>` for more information. 204 205* The search index file is now generated with the ``build-index`` command that has been rewritten in Python. ``build-index.sh`` is still available but is just an alias to ``build-index``. 206 207* The ``CONTENT_DIR`` setting has been replaced with ``STATIC_ROOT`` and now allows to easily serve non-graphite static files such as Django admin's. See the :doc:`configuration docs <../config-local-settings>` for usage instructions. 208 209* `Tox <https://testrun.org/tox/latest/>`_ is now used for running the tests locally across the supported Django and Python version combinations. A :doc:`section about working on graphite-web <../development>` has been added to the documentation. 210 211* Python's own log rotation can be disabled using the `LOG_ROTATION` setting. This is useful when running multiple WSGI workers. 212 213* The events API now requires ``tags`` to be an array when creating tagged events. Previous versions only accepted string attributes. Tags are also serialized as arrays. 214 215* Enhancements and optimizations to brace expansion for wildcards. 216 217* Graphite Dashboards support absolute time ranges passed in the URL. 218 219* Dumping the known metrics list with ``/metrics/index.json`` now includes RRD metrics. 220 221* Improved support for special characters in metric names. 222 223* Support for jsonp requests in the metrics view. 224 225* New "refresh" button in the metrics tree navigation panel. 226 227* Refresh all visible nodes in the metrics tree navigation view, not just the current node level. 228 229* Support for globstar matching in target paths. 230 231* Introduce the ``MAX_TAG_LENGTH`` setting for overriding the maximum tag length for events. 232 233* Ability to retrieve a single event via the API. Previously you would have to dump the entire events database to inspect any events. 234 235* Configurable ``DATE_FORMAT`` setting for overriding the short date format. 236 237* New ``nodelist`` format for the metrics find view. This mode makes it easier for clients to query metric node information from the API. 238 239* Ability to pass units suffix string (e.g. "Kb") to ``cactiStyle``. 240 241* Interpolate across null values in ``perSecond`` function. 242 243* Dashboards are now sorted alphabetically in the finder. 244 245* Support for unicode in rendered graph text. 246 247* Improved sorting of saved graphs. 248 249* Event times are now converted to local time to align with query times. 250 251* Faster calculation algorithm for ``movingAverage``. 252 253* Automatically close the Dashboard's upper navigation panel if the dashboard was loaded by a parameterized URL. 254 255* Cluster servers can now communicate over HTTPS when ``INTRACLUSTER_HTTPS`` is enabled. 256 257* Readers are more resilient to the loss of a single backend 258 259* Support whisper aggregation method "last" 260 261* Improve json rendering performance 262 263* Allow to override Memcache options easily 264 265* Make readers.py more easilly importable by moving away models 266 267* Support 0.9.x backends in 1.0.0 cluster 268 269* hange deprecated request.REQUEST 270 271* Decreasing number of stat syscalls dramatically using `scandir` module 272 273* Add json format option for find api 274 275* Forward HTTP request headers to CLUSTER_HOSTS 276 277* Pre-load each graph image before updating the dashboard UI 278 279* Fix incorrect display of 'title' URI parameter 280 281* prevent repeated series evaluations for hitcount and smartSummarize 282 283Carbon 284^^^^^^ 285 286* Support for pluggable protocols and clients. Support for protobuf was added, existing protocols have been ported over to use the new design. 287 288* Support for pluggable routers, including new ``fast-hashing`` and ``fast-aggregated-hashing`` relay methods based on MurmurHash3. 289 290* Introduced ``CERES_NODE_CACHING_BEHAVIOR`` for tuning Ceres' caching behavior. 291 292* Aggregators now report ``destinations`` statistics. 293 294* Remove unused ``list`` and ``match-all`` schema options. 295 296* Introduced ``WHISPER_FADVISE_RANDOM`` as an option to avoid disk thrashing in certain scenarios. 297 298* Support for ``MAX_RECEIVER_CONNECTIONS`` to limit the number of TCP connections to the intended Carbon service. 299 300* Listeners will include metric path details when logging due to invalid line submission. 301 302* Support logging to syslog with the ``--syslog`` runtime option. 303 304* Allow Manhole to operate with no passphrase. 305 306* New ``--profiler`` runtime option for specifying the profiler. 307 308* Improved ``HUP`` signal handling. 309 310* Add support for IPv6 addresses enclosed in square brackets in the destination parser. 311 312* Add LOG_CREATES to disable creation logs 313 314* Enforce better syslog tag 315 316* Update carbon.amqp.conf.example 317 318* Add protobuf support 319 320* Add MIN_TIMESTAMP_RESOLUTION 321 322* Fix CACHE_WRITE_STRATEGY and add TimeSortedStrategy 323 324Whisper 325^^^^^^^ 326 327* Add fallocate and sparse support in whisper-create 328 329* use whisper-resize if whisper-resize.py is not available 330 331* Support FADVISE_RANDOM for create/update/update_many 332 333* rrd2whisper.py: Only suffix wsp files if required 334 335* whisper-fill: move to optparse, add whisper file locking 336 337* whisper-auto-resize.py: allow subdir to be a single file 338 339* Faster evaluation for 'last' aggregation method 340 341* Add update-storage-times.py - a tool to change storage schemas for whisper files and update the data. Threaded to vastly improve speed over whisper-auto-resize.py 342 343* whisper: disable buffering for update operations 344 345* whisper-diff improvement: new until param 346 347* Add optional destinationPath for rrd2whisper 348 349* added json output to whisper-diff.py script 350 351* setup: install contrib scripts 352 353* Make indentation consistent in files with mixed indentation 354 355* Add whisper-set-xfilesfactor.py utility 356 357* parseRetentionDef: raise more descriptive exception on wrong retention 358 359* whisper resize: don't attempt to merge empty files 360 361* whisper-fetch whisper-auto-update: validate if whisper.fetch() returned data