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