The design and description of the feature is documented in the .md file in https://review.gluster.org/16357. When the change is merged, the file will be available under https://github.com/gluster/glusterfs-specs/tree/master/done/GlusterFS%203.10 More practical details are also mentioned in https://github.com/gluster/glusterfs/blob/master/doc/debugging/statedump.md
I think the following section in the Administration Guide needs to be updated: 19.8. Performing Statedump on a Volume [1] Specifically, we need to document how to take statedump for gfapi applications using the following command: # gluster volume statedump <vol> <host>:<pid> Niels, Can you confirm if my understanding is correct? Is there anything else we should tell users about this feature? https://github.com/gluster/glusterfs/blob/master/doc/debugging/statedump.md page has lot of information on how to use statedump data in debugging/troubleshooting. I am planning to raise a doc RFE to add this in the Admin Guide. Do you think it would help users? [1] http://ccs-jenkins.gsslab.brq.redhat.com:8080/job/doc-Red_Hat_Gluster_Storage-3.2-Administration_Guide-branch-master/lastSuccessfulBuild/artifact/tmp/en-US/html-single/index.html#Performing_Statedump_on_a_Volume
Yes, this is an addition to the last part of that section. > To retrieve the statedump information for client processes: > > kill -USR1 process_ID Applications using gfapi are client processes, but gfapi may not handle the signals (like USR1) because the applications should handle them. This prevented creating statedumps from gfapi-client (NFS-Ganesha, Samba, QEMU, ...) processes before. After executing the command, the statedump will be written to /var/run/gluster, just like with other client processes. You should note that the user running the application requires write permissions to /var/run/gluster. gfapi applications do not require running as root, and for this a group "gluster" has been created. The user running the application (in case of QEMU this is the "qemu" user) needs to be added to the "gluster" group. A command like this would do: # usermod -a -G gluster qemu [Bug 1447694 has been filed to get this done in the QEMU packaging for RHV.] Note that QEMU is just one example, admins can configure applications to run as any user they like. Also users that run applications that use gfapi and need the advanced debugging options with statedumps should be added to the "gluster" group. There is no need for users to understand the contents of the statedump itself. This is purely a Gluster internal mechanism used for troubleshooting and debugging. The note about statedumps in the documentation is more intended for GSS/CEE and less for customers.
Thanks for your inputs Neils. Based on your inputs and my discussion with Sas, I have updated the documentation. Link to the draft doc: https://access.qa.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html-single/administration_guide/#Performing_Statedump_on_a_Volume Could you please review and confirm if the updates are fine? After your confirmation, I will move the bug ON_QA. Thanks!
That looks good to me. Thanks Divya!
Thanks for the confirmation, Niels! I have documented how to take statedump for gfapi applications. A note has been added about the "gluster" group as well. Link to the draft doc: https://access.qa.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html-single/administration_guide/#Performing_Statedump_on_a_Volume Moving the bug ON_QA.
Content looks good, however need to modify the introductory statements in two places Change-1 ---------- <existing_content> 19.8.2. Gathering information from the client You can see the state of volume processes on the client by running the following command: </existing_content> <expected> 19.8.2. Gathering information from the client To generate statedump for the processes, using libgfapi, below command can be executed from one of the nodes in the gluster cluster to which the libgfapi application is connected to. </expected> change-2 ---------- <existing_content> If you need to see the state of a different process, you can do so by running the following command using the process identifier of that process. </existing_content> <existing_content> If you need to get the state of glusterfs fuse mount process, you can do so by running the following command using the process identifier of that process. </existing_content>
Typo > > change-2 > ---------- > <existing_content> > If you need to see the state of a different process, you can do so by > running the following command using the process identifier of that process. > </existing_content> > <expected> > If you need to get the state of glusterfs fuse mount process, you can do so > by running the following command using the process identifier of that > process. </expected>
I have made the changes suggested in comment 8. Link to the updated documentation[1] NOTE:For now the changes are available only on the Topic branch. The merge request is pending. Link to that MR[2]. [1] http://ccs-jenkins.gsslab.brq.redhat.com:8080/view/Topic%20branches%20-%20Gluster/job/doc-Red_Hat_Gluster_Storage-3.3-Administration_Guide-branch-BZ-1436678-gfapi/lastSuccessfulBuild/artifact/tmp/en-US/html-single/index.html#Viewing_complete_volume_state_statedump [2] https://gitlab.cee.redhat.com/red-hat-gluster-storage-documentation/3.3-Administration_Guide/merge_requests/69
Verified with the doc link available in [1] of comment10