Make error messages more useful: add a URI

[Nico Williams]

On Thu, Oct 02, 2014 at 03:00:03PM -0400, Greg Hudson wrote:
> In general I am an error message minimalist; I think error messages
> should be useful, but also readable.  I do not generally see URIs or
> unique identifiers in the error messages reported by my applications
> and tools; in the rare cases where I do, it tends to make me feel like
> the application is clunky.

FWIW, Solaris' SMF and FMA use URIs in their error messages.

Without a URI all you have is search engines and the text error.  The
pithier the error, the more difficult to search.  Either way you have a
search and it will take time and effort to find your way.  "Use the docs
Luke" is not a good answer for most users.

But with a URI the user just clicks (at worst cuts-n-pastes) and there,
they have all the info they need.  Site-specific pages could have
site-specific diagnostic and corrective action information.

> But I am open to the possibility that I'm wrong-headed about this.

"Wrong-headed" is a bit strong.  This shouldn't be necessary, but
site-specific Kerberos practices vary a *lot*, and that's what's causing
me to propose this at all.

I'm being asked to express error messages that I am certain you'd not
accept (e.g., "No Kerberos credentials available: KRB5CCNAME not set and
default ccache (/tmp/krb5cc_...) does not exist").

I expect you to reject such errors for the same reasons that I would
reject them were I in your shoes.  Not every environment that uses GSS
will use Kerberos, not every Kerberos shop will expect KRB5CCNAME to be
set at all times, not every Kerberos shop will use FILE ccaches, and so
on.  But you can see how a URI would allow us to customize the
information shown to users on a site-specific basis.

(In some environments not having KRB5CCNAME set is effectively an error
condition, often arising from [unfortunate] overuse of LD_LIBRARY_PATH
(and other *PATH variables) that then leads to overuse of env -i and
losing precious variables.  In such environments the absence of
KRB5CCNAME from the environment is quite indicative of erroneous wiping
of the environment, thus it's very useful diagnostic information.  In
other environments having error messages from libkrb5 say anything about
KRB5CCNAME would be distracting.)

Customizable errors (site-specific localization, as it were) would also
help (since one could then have them mention KRB5CCNAME where that's
desirable).  But that seems to be potentially more difficult to
implement, and even so would require changes to how ENOENT is handled in
ccfile.c you might still look at askance.  Though perhaps you'd prefer
this, in which case I'd be happy to take this route.

> Regardless, it would be a lot of work to create a backing set of
> useful documentation about each error code or format string.  Often,
> it's not possible to provide useful advice without knowing more about
> the context which led to the error.

You'd not have to write such pages: by default you might not generate
URIs.  And all URIs might well lead to just a common page.  But in some
environments we might gladly write such pages.

Nico
--