== Summary == [http://dag.wiee.rs/home-made/dstat/ Dstat] is a resource statistics tool for the local host. [https://pcp.io Performance Co-Pilot] is a system performance analysis toolkit.
This change will merge the existing python2 '''dstat''' utility and associated ''dstat'' package into the ''pcp-system-tools'' package where a python3 implementation is provided.
A symbolic link and package replacement rules will streamline the transition.
== Owner == * Name: [[User:nathans| Nathan Scott]] * Email: nathans@redhat.com * Name: [https://src.fedoraproject.org/user/dkaspar David Kaspar] * Email: dkaspar@redhat.com
== Detailed Description ==
The original '''dstat''' utility has reached end of life - it does not support python3 and there are no plans to update it. It has been unsupported upstream for some time. However, it is a widely used and much loved tool. The Performance Co-Pilot (PCP) project has produced a '''pcp-dstat''' utility which strives for 100% output compatibility with the original '''dstat'''.
The new '''pcp-dstat''' utility displays metric values and metadata (e.g. units) by accessing the PCP python APIs. This utility was first included in PCP version 4.1.0 which is now available in all supported Fedora versions, in the ''pcp-system-tools'' package. It is invoked as: 'pcp dstat'.
This proposed change will transition Fedora to provide ''/usr/bin/dstat'' as a symbolic link to the ''pcp-dstat'' script, and will deprecate the original dstat package which requires python2.
== Benefit to Fedora ==
There are several benefits. First and foremost - the original motivation - we are able to continue to provide the primary dstat functionality in a python3-based system.
In addition to providing the same compact, colourful output that the original dstat provided, the new utility also supports distributed analysis (monitoring one host from another) using PCP protocol, and retrospective analysis via Performance Co-Pilot archives.
A configuration file format for plugins has been introduced to '''pcp-dstat'''(1). This was on the original dstat roadmap for many years, but not implemented. Because PCP metrics can be accessed by name, and have strong metadata (including units), a generalised plugin configuration is possible which allows pcp-dstat to display any Performance Co-Pilot metric values. All of the original '''dstat''' "builtin" plugins as well as many of the "extended" plugins are provided by these configuration files, below the ''/etc/pcp/dstat'' directory.
Customised plugins are encouraged and supported in '''pcp-dstat''' just as they were in the original '''dstat''', except these are now configuration files rather than python code.
== Scope == * Proposal owners: The primary goal has been accomplished - providing the python3 pcp-dstat utility. The remaining effort involves ensuring a clean transition through packaging updates. The pcp-system-tools package will need to provide a spec file Obsoletes line and symbolic link in /usr/bin/dstat to complete the transition - this final stage of work has not yet been done.
* Other developers: N/A (not a System Wide Change)
* Release engineering: [https://pagure.io/releng/issues #7648]
* Policies and guidelines: N/A (not a System Wide Change)
* Trademark approval: N/A (not needed for this Change)
== Upgrade/compatibility impact == On upgrade, a system with ''dstat'' installed will be seamlessly transitioned to using the ''pcp-system-tools'' package. The command output format is the same.
The original dstat provided a facility for adding new (python2 code) 'plugins' to provide user-customisable metric reports. This feature remains, but instead uses the configuration files for providing this extension. Performance Co-Pilot allows arbitrary metrics to be added to the framework as well (via PMDAs - Performance Metric Domain Agents).
The upstream PCP mailing list, books, man pages and tutorials can be used for anyone wishing to add new metrics, which will then be automatically available to '''pcp-dstat''' configuration files for displaying.
== How To Test ==
1. Install pcp-system-tools
2. Verify that ''/usr/bin/dstat'' is now a symbolic link to '''pcp-dstat''' and that the ''dstat'' package is no longer installed.
3. Run '''dstat''' and compare the output to the original dstat utility.
== User Experience == Users of the dstat utility will have an improved analysis experience using pcp-dstat, as not only is it more easily extended through configuration files instead of python2 code, it also offers distributed (remote hosts) and retrospective (historical) analysis capabilities that the original utility does not provide.
== Dependencies == The ''pcp-system-tools'' package depends on ''python3-pcp'', which in turn depends on ''pcp-libs'' and ''python3''.
== Contingency Plan ==
* Contingency mechanism: (What to do? Who will do it?) N/A (not a System Wide Change) * Contingency deadline: N/A (not a System Wide Change) * Blocks release? N/A (not a System Wide Change) * Blocks product? No
== Documentation == The new version of the utility is documented in the '''pcp-dstat'''(1) and '''pcp-dstat'''(5) man pages, in the ''pcp-doc'' package.