-------------------------------------------------------------------------------
fsstat(1m) stability update and interface tweak
Dan Price (dp@eng)

Advising: Rich Brown (Rich.Brown@Sun.COM), Jeff Bonwick (bonwick@eng)

Introduction
------------

Early feedback on and experience with the fsstat [1] utility has shown that
it is in need of further refinements, particularly with respect to non-global
Zones [2].  This case seeks to make room in fsstat for future improvements in
Solaris Update releases.

Interface Table
---------------

                          Current             Proposed            Proposed
  Entity                  Stability            (patch)     (minor release)
-----------------------------------------------------------------------------
  fsstat(1m) CLI           Evolving           Unstable            Evolving
  fsstat(1m) Output        Unstable   Not an Interface    Not an Interface
  fsstat(1m) -P Output     Unstable            Removed            Removed*
  vopstats_{fstype|fsid} Cons Priv.         Cons Priv.          Cons Priv.

  * Our intention is that fsstat -P will reappear in a future revision
    of this tool, which will be the subject of a future case.

(Note that the current fsstat man page in build 35 incorrectly documents
 the stability of the command.  This is being fixed.)

Background
----------

The concerns about fsstat raised thus far are listed later in this case.
We are *not* asking for architectural feedback on these concerns; rather
illustrating that they exist and that the parties involved have
acknowledged and discussed them.

Due to intense time to market pressure communicated by the ZFS team,
fsstat has not undergone the usual long Solaris beta cycle, and will
ship in Update 2.  The ZFS team has emphasized that the utility of
the fsstat command justifies its presence in the product even though we
expect its output to change.  We believe that this is one of the most
important changes to observability in Solaris Nevada, and thus deserves
leeway to soak and mature further.

After further review from the project team, the ZFS team, and the Zones
team, it was decided that we seek PSARC approval to note to customers
that this utility may change substantially in a future update release,
and to remove the default output of the command so that it can be
populated at a later date, as well as to remove the parseable output.
We have discovered that we lack sufficient customer feedback to know
exactly what "mode" default output should reflect.

Proposal
--------

Members of the project team, the ZFS team, and the Zones team have
cooperated to reach this agreement.  This solution represents the best
compromise of architectural flexibility and time-to-market needs.

  - Change the default output of fsstat to print the usage
    message.  Move the current default behavior (an aggregated
    view by filesystem module name) to a new -F option.

  - Alter CLI stability of fsstat in the current patch release (i.e.
    Solaris 10 Updates) to Unstable [3] to allow us the flexibility
    to incompatibly revise fsstat in the current minor release
    (i.e. Nevada).  Immediately prior to the release of Solaris
    Nevada, the stability will rise to Evolving.

  - Remove the parseable output of fsstat until we have greater
    experience with the command.

  - Alter the output stability of the human readable output of 
    fsstat to "Not an Interface."

  - Document in that man page that fsstat is not suitable for
    the construction of higher level software tools at this time
    (i.e. don't parse its output).

The kstats which fsstat consumes are not altered in any way by this
case.

fsstat(1m) Concerns
-------------------

Concerns registered thus far are documented in this section.  These are
for informational purposes; we don't want to debate them here as we
have not yet had time to study them in depth:

  - The default output is unsuitable in current form for Solaris
    Zones, since it reveals system-wide activity.  While not a security
    problem, the output is essentially nonsensical for non-global zones.

  - The zones team has provided the advice that at least for
    zones, admins are going to want to understand how each
    mount is behaving; they are less likely to be concerned about
    UFS vs. ZFS activity levels.

  - The default output of the command may yield information
    that is difficult for admins to make sense of (the theory is
    that most admins do not think in terms of filesystem module
    type).

  - A more suitable default output may be to follow the model of
    prstat, and sort the output by activity.  Further study and
    prototyping are needed.

  - Use of human-readable numbers (i.e. 1.1M, 2.5K, 9.9G) actually
    obscures which numbers are big or small.

References
----------

[1] PSARC 2006/034 fsstat
[2] PSARC 2002/174 Virtualization and Namespace Isolation in Solaris
[3] PSARC 2005/185 "Enabling Serendipitous Discovery." Opinion, section 4.3.
-------------------------------------------------------------------------------