Fedora 29 Self-Contained Change: Merge Dstat And Performance Co-Pilot

[Ben Cotton]

== 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(a)redhat.com
* Name: [https://src.fedoraproject.org/user/dkaspar David Kaspar]
* Email: dkaspar(a)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.


-- 
Ben Cotton
Fedora Program Manager
TZ=America/Indiana/Indianapolis