.. _1-0-0:

1.0.0

04/12/2017

Graphite 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.

Most users will only need to install the Graphite-Web, Carbon, and Whisper components.

Source bundles are available from GitHub:

• https://github.com/graphite-project/graphite-web/archive/1.0.0.tar.gz
• https://github.com/graphite-project/carbon/archive/1.0.0.tar.gz
• https://github.com/graphite-project/whisper/archive/1.0.0.tar.gz
• https://github.com/graphite-project/carbonate/archive/1.0.0.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/

Upgrading

Graphite-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 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.

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 --run-syncdb

A new document is available for :doc:developers and contributors <../development> that covers how to setup your own development environment, and running & writing tests.

We'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.

Security Notes

• XSS issue affecting saved graph definitions. Targets are now properly sanitized before being handed back to the user.

New Render Functions

See the :doc:functions documentation <../functions> for more information.

• aggregateLine
• applyByNode
• averageOutsidePercentile
• delay
• exponentialMovingAverage
• fallbackSeries
• grep
• groupByNodes
• integralByInterval
• interpolate
• invert
• isNonNull
• linearRegression
• linearRegressionAnalysis
• mapSeries
• movingMin
• movingMax
• movingSum
• multiplySeriesWithWildcards
• offsetToZero
• pow
• powSeries
• reduceSeries
• removeBetweenPercentile
• removeEmptySeries
• sortByTotal
• squareRoot
• timeSlice
• verticalLine
• weightedAverage

New Display Formats

• pdf
• dygraph
• rickshaw

New Graph Parameters

• hideNullFromLegend
• hideXAxis
• noNullPoints
• pieLabels
• valueLabels
• valueLabelsColor
• valueLabelsMin

Bug Fixes

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

• Render infinite values correctly for compatibility with JSON consumers (e.g. Grafana).

• Fix for aliasByMetric to handle trailing parentheses properly.

• Some functions would not handle event tags formatting. The format for these strings has been fixed.

• Improved data extraction from CarbonLink cache when crossing archive boundaries.

• Follow symlinks for RRD files.

• Unicode fixes for RRD paths.

• Support for the FNV1a_ch hashing algorithm used by the carbon-c-relay <https://github.com/grobian/carbon-c-relay>_ project.

• Fix for smartSummarize where it would discard timezone information, sometimes resulting in an exception due to broken intervals.

• Better handling for missing data in the divisor series for divideSeries.

• Fix function name reported in path expression for stdev.

• The countSeries function will now return zeroes instead of an empty series.

• The constantLine function can now be rendered without any other series.

• Incorrect float format across a variety of functions.

• Fix "thousands" unit for y-axis.

• Average/current/max/min Above/Below functions not fails if there is no data.

• Fix blank space below the legend

• Update the command to setup a new database

• aliasByNode(): support all chars allowed by the grammar

Carbon ^^^^^^

• Avoid duplication of aggregator statistics by using a dedicated pipeline.

• Log incorrect schemas missing the retentions attribute.

• Improved logging for writer create or update failures.

• Fix long-standing issue with negative cache size statistic.

• Use the correct AGGREGATION_RULES configuration file.

• Fix race condition possible when queue is full and destinations reconnect.

• Fix --profile option for recording performance data.

• Improved help documentation in the Composer.

• Compute seconds_left rightly in util.

• Better handling for failed creates.

• Import manhole and amqp correctly

• Fix CacheManagementHandler() and associated tests

Whisper ^^^^^^^

• remove xFilesFactor float comparison, use whisper-resize if whisper-resize.py is not available

• (fix) [FreeBSD-i386] correct size of off_t in posix_fallocate call

• whisper-auto-resize.py: error fix

• double-fix bad commit to whisper-resize

• whisper-auto-resize: fix default values for xFilesFactor and aggregationMethod

• Fix indentation on CACHE_HEADERS, not related to AUTOFLUSH

• rrd2whisper: fix relative destinationpaths

Other Changes

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

• Brand new clustering implementation using a pool of worker threads and persistent connections to backends

• New Graphite logo in the Composer banner.

• 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.

• 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.

• 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.

• 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.

• Python's own log rotation can be disabled using the LOG_ROTATION setting. This is useful when running multiple WSGI workers.

• 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.

• Enhancements and optimizations to brace expansion for wildcards.

• Graphite Dashboards support absolute time ranges passed in the URL.

• Dumping the known metrics list with /metrics/index.json now includes RRD metrics.

• Improved support for special characters in metric names.

• Support for jsonp requests in the metrics view.

• New "refresh" button in the metrics tree navigation panel.

• Refresh all visible nodes in the metrics tree navigation view, not just the current node level.

• Support for globstar matching in target paths.

• Introduce the MAX_TAG_LENGTH setting for overriding the maximum tag length for events.

• Ability to retrieve a single event via the API. Previously you would have to dump the entire events database to inspect any events.

• Configurable DATE_FORMAT setting for overriding the short date format.

• New nodelist format for the metrics find view. This mode makes it easier for clients to query metric node information from the API.

• Ability to pass units suffix string (e.g. "Kb") to cactiStyle.

• Interpolate across null values in perSecond function.

• Dashboards are now sorted alphabetically in the finder.

• Support for unicode in rendered graph text.

• Improved sorting of saved graphs.

• Event times are now converted to local time to align with query times.

• Faster calculation algorithm for movingAverage.

• Automatically close the Dashboard's upper navigation panel if the dashboard was loaded by a parameterized URL.

• Cluster servers can now communicate over HTTPS when INTRACLUSTER_HTTPS is enabled.

• Readers are more resilient to the loss of a single backend

• Support whisper aggregation method "last"

• Improve json rendering performance

• Allow to override Memcache options easily

• Make readers.py more easily importable by moving away models

• Support 0.9.x backends in 1.0.0 cluster

• hange deprecated request.REQUEST

• Decreasing number of stat syscalls dramatically using scandir module

• Add json format option for find api

• Forward HTTP request headers to CLUSTER_HOSTS

• Pre-load each graph image before updating the dashboard UI

• Fix incorrect display of 'title' URI parameter

• prevent repeated series evaluations for hitcount and smartSummarize

Carbon ^^^^^^

• Support for pluggable protocols and clients. Support for protobuf was added, existing protocols have been ported over to use the new design.

• Support for pluggable routers, including new fast-hashing and fast-aggregated-hashing relay methods based on MurmurHash3.

• Introduced CERES_NODE_CACHING_BEHAVIOR for tuning Ceres' caching behavior.

• Aggregators now report destinations statistics.

• Remove unused list and match-all schema options.

• Introduced WHISPER_FADVISE_RANDOM as an option to avoid disk thrashing in certain scenarios.

• Support for MAX_RECEIVER_CONNECTIONS to limit the number of TCP connections to the intended Carbon service.

• Listeners will include metric path details when logging due to invalid line submission.

• Support logging to syslog with the --syslog runtime option.

• Allow Manhole to operate with no passphrase.

• New --profiler runtime option for specifying the profiler.

• Improved HUP signal handling.

• Add support for IPv6 addresses enclosed in square brackets in the destination parser.

• Add LOG_CREATES to disable creation logs

• Enforce better syslog tag

• Update carbon.amqp.conf.example

• Add protobuf support

• Add MIN_TIMESTAMP_RESOLUTION

• Fix CACHE_WRITE_STRATEGY and add TimeSortedStrategy

Whisper ^^^^^^^

• Add fallocate and sparse support in whisper-create

• use whisper-resize if whisper-resize.py is not available

• Support FADVISE_RANDOM for create/update/update_many

• rrd2whisper.py: Only suffix wsp files if required

• whisper-fill: move to optparse, add whisper file locking

• whisper-auto-resize.py: allow subdir to be a single file

• Faster evaluation for 'last' aggregation method

• 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

• whisper: disable buffering for update operations

• whisper-diff improvement: new until param

• Add optional destinationPath for rrd2whisper

• added json output to whisper-diff.py script

• setup: install contrib scripts

• Make indentation consistent in files with mixed indentation

• Add whisper-set-xfilesfactor.py utility

• parseRetentionDef: raise more descriptive exception on wrong retention

• whisper resize: don't attempt to merge empty files

• whisper-fetch whisper-auto-update: validate if whisper.fetch() returned data