From 7786f61ccd1ebeb842aca26456b6fdeda40bf97c Mon Sep 17 00:00:00 2001 From: Amar Tumballi Date: Tue, 6 Feb 2018 19:23:28 +0530 Subject: doc: updated the release-notes Change-Id: I481a0041393acf556f4c6ab15ee74e4c8e3dea50 Signed-off-by: Amar Tumballi --- doc/release-notes/4.0.0.md | 133 ++++++++++++++++++++++++++++++--------------- 1 file changed, 90 insertions(+), 43 deletions(-) (limited to 'doc') diff --git a/doc/release-notes/4.0.0.md b/doc/release-notes/4.0.0.md index c7757f0ed02..8dbfd95624e 100644 --- a/doc/release-notes/4.0.0.md +++ b/doc/release-notes/4.0.0.md @@ -44,30 +44,47 @@ Features are categorized into the following sections, **Known Issues:** ### Monitoring -#### 1. More metrics on fops at every translate layer -**Notes for users:** -- https://github.com/gluster/glusterfs/issues/137 -- Release notes needs: - - Needs appropriate documentation - - Also, need some developer documentation to aid in debugging using this information -**Limitations:** +The lack of live monitoring support on top of GlusterFS till date was a +limiting factor for many users (and in many cases for developers too). +[Statedump](docs.gluster.org/en/latest/Troubleshooting/statedump/) did some work of helping during debugging, but was heavy for +live monitoring. +Further, the existence of `debug/io-stats` translator was not known to many and +`gluster volume profile` was not recommended as it took a hit on performance. -**Known Issues:** +With this release, glusterfs's core infrastructure itself gets some mechanisms +to provide internal information, that avoids the heavy weight nature of prior +monitoring mechanisms. -#### 2. Monitoring support +#### 1. Metrics collection across every FOP in every xlator **Notes for users:** -- https://github.com/gluster/glusterfs/issues/168 -- Usage needs documentation -- Release notes: - - Need documentation to point to and some terse statement for the release notes +Gluster, with this release, has in-built latency measures in the xlator +abstraction, thus enabling capture of metrics and usage patterns across +workloads. + +These measures are currently enabled by default. **Limitations:** +This feature is auto-enabled and cannot be disabled. +Providing means to disable the same in future releases also may not be made +available, as the data generated is deemed critical to understand and +troubleshoot gluster usage patterns. -**Known Issues:** +#### 2. Monitoring support +**Notes for users:** +Currently, only project which consumes the metrics and provides basic +monitoring is [glustermetrics](https://github.com/amarts/glustermetrics), which provides a good idea on how to +utilize the metrics dumped from the processes. +Users can send SIGUSR2 signal to the process to dump the metrics, in +`/var/run/gluster/metrics/` directory. + +**Limitations:** +Currently core gluster stack and memory management systems dump metrics. For +other translators and other core components, framework to provide more metrics +exists, but additional metrics are not added in this release. ### Performance #### 1. EC: Make metadata [F]STAT/[F]GETXATTR operations faster @@ -220,25 +237,35 @@ Features are categorized into the following sections, #### 3. Dentry fop serializer xlator on brick stack **Notes for users:** -- https://github.com/gluster/glusterfs/issues/397 -- Release notes: - - Needs option documentation and when to use the same comments +This feature strengthens consistency of the file system, trading it for some +performance and is strongly suggested for workloads where consistency is +required. -**Limitations:** +For use-cases that involve a large number of renames or frequent creations and +deletions, the meta-data about the files and directories shared across the +clients were not always consistent. They do eventually become consistent, but +a large proportion of applications are not built to handle eventual consistency. +This feature can be enabled as follows, +``` +# gluster volume set features.sdfs enable +``` -**Known Issues:** +**Limitations:** +This feature is released as a preview, as performance implications are not known +completely. #### 4. Add option to disable nftw() based deletes when purging the landfill directory **Notes for users:** -- https://github.com/gluster/glusterfs/issues/371 -- Release notes: - - Document option to use and when to use the same - -**Limitations:** +The gluster brick processes use an optimized manner of deleting entire sub-trees +using the nftw call. With this release, an option is being added to toggle this +behavior in cases where this optimization is not desired. +This is not an exposed option, and needs to be controlled using the volume +graph. Adding the disable-landfill-purge option to the storage/posix translator +helps toggle this feature. -**Known Issues:** +The default is always enabled, as in the older releases. #### 5. Add option in POSIX to limit hardlinks per inode **Notes for users:** @@ -266,10 +293,18 @@ Features are categorized into the following sections, ### Developer related #### 1. xlators should not provide init(), fini() and others directly, but have class_methods **Notes for developers:** -- https://github.com/gluster/glusterfs/issues/164 -- Some developer documentation needs to be updated for this change -- Release notes: - - Can be handled by the release team +This release brings in a new unified manner of defining xlator methods. Which +avoids certain unwanted side-effects of the older method (like having to have +certain symbols being defined always), and helps a cleaner single point +registration mechanism for all xlator methods. + +The new method, needs just a single symbol in the translator code to be exposed, +which is named xlator_api. + +The elements of this structure is defined [here](https://github.com/gluster/glusterfs/blob/release-4.0/libglusterfs/src/xlator.h#L1055) and an example usage of the +same can be seen [here](https://github.com/gluster/glusterfs/commit/5b4b25c697f93d3dfe352013a442f2ec73fd3b8b). + +The older mechanism is still supported, but not preferred. #### 2. Framework for distributed testing **Notes for developers:** @@ -287,10 +322,21 @@ Features are categorized into the following sections, #### 4. New on-wire protocol (XDR) needed to support iattx and cleaner dictionary structure **Notes for developers:** -- https://github.com/gluster/glusterfs/issues/384 -- Requires some developer writeup, to explain out the changes -- Release notes: - - Can point to developer notes, if made available +With changes in the code to adapt to a newer iatt structure, and stricter data +format enforcement within dictionaries passed across the wire, and also as a +part of reducing technical debt around the RPC layer, this release introduces a +new RPC Gluster protocol version (4.0.0). + +Typically this does not impact any development, other than to ensure that newer +RPCs that are added would need to be on the 4.0.0 version of the protocol and +dictionaries on the wire need to be better encoded. + +The newer iatt structure can be viewed [here](https://github.com/gluster/glusterfs/blob/release-4.0/libglusterfs/src/iatt.h#L47). + +An example of better encoding dictionary values for wire transfers can be seen +[here](https://github.com/gluster/glusterfs/blob/release-4.0/libglusterfs/src/dict.c#L2454). + +[Here](https://github.com/gluster/glusterfs/blob/master/doc/developer-guide/rpc-for-glusterfs.new-versions.md) is some additional information on Gluster RPC programs for the inquisitive. #### 5. Leases support on GlusterFS **Notes for developers:** @@ -303,19 +349,20 @@ Features are categorized into the following sections, **Notes for developers:** - https://github.com/gluster/glusterfs/issues/203 - Release notes: - - Pont to developer documentation if any + - Point to developer documentation if any #### 7. Translator to handle 'global' options **Notes for developers:** -- https://github.com/gluster/glusterfs/issues/303 -- Release notes: - - Needs developer documentation for future improvements in this area +GlusterFS process has around 50 command line arguments to itself. While many of +the options are initial settings, many others can change its value in volume +lifetime. Prior to this release there was no way to change a setting, other than +restarting the process for many of these options. -#### 8. Information on RPC programs -**Notes for developers:** -- https://github.com/gluster/glusterfs/issues/140 -- Release notes: - - Point to the provided documentation +With the introduction of global option translator, it is now possible to handle +these options without restarts. + +If contributing code that adds to the process options, strongly consider adding +the same to the global option translator. An example is provided [here](https://review.gluster.org/18316). ## Major issues @@ -325,4 +372,4 @@ Features are categorized into the following sections, Bugs addressed since release-3.13.0 are listed below. -**TBD** \ No newline at end of file +**TBD** -- cgit